Technical writing/Tools

Working together is what counts.

back to Technical Writing Level 2

Tools are only tools...

This Technical Writing course focuses on methods and processes that are tool-independent. Organizing writing, editing, and graphics in a usable manner is your primary task and is essential to the user experience.

The primary tools a technical writer needs are:

• Interpersonal skills. If you cannot get along with people, you have no chance of succeeding as a technical writer.
• Language skills. Your English (or other language) must be of a very high level. You must be constantly reading, learning, and improving your writing style.
• Curiosity. Technical writing is about learning, and then passing on what you have learned. You must have an unending desire to know new things.
• Organizational skills. Unstructured data is useless. You must be able to take a mass of facts and turn them into understandable information.

There are a number of tools that have been developed over the years specifically for the job of technical communications. In this section we will discuss these tools.

Screen Grabs

The Value of Screenshots

Visuals in technical writing are important.

• According to "a study on learning using a 94-page manual versus using 25 flash cards....people learned more quickly with the flash cards that covered key ideas and hints, and [not by] step-by-step instruction."

• This anecdote from Kim Nathans illustrates most users' reaction to documentation:

"I got my first actual feedback from a new employee (Director of Development) and he was disappointed that I didn’t include a pictorial storyboard of the process flow. It turns out that he didn’t so much read any of my documentation as he just glanced at it. I started thinking about how many of the consumers of this documentation will be like him, and was depressed to realize that there will probably be a lot more like him than like me (a compulsive reader who will read every word in front of her face).

I asked a marketing intern in our office for his opinion, and he pulled out a very dog-eared and obviously well-used document that he had printed out. It was nearly all screen shots with certain UI items circled sloppily (like they’d used a mouse to do it freehand). He enthused for a couple of minutes about this being the most useful piece of documentation he’s ever had, because he can quickly refer to it and easily find the steps he needs to take to accomplish whatever task it conveyed."

• Tom Johnson comments that:

"In communicating conceptual information, it’s extremely important to reinforce concepts with visuals. Not just screenshots, but diagrams. This is one reason I’m dipping into Visio more heavily. Diagrams, not just screenshots, help users understand concepts much better."

• All the quotes in this section are taken from Rethinking the Importance of Screenshots by Tom Johnson. Used with permission.

Why use a Screen Grab Tool

When writing technical documentation you will often need to take screenshots or screen 'grabs' to embed into the document. This can be for a variety of reasons, whether to provide a visual reference for the documentation or to provide visual step-by-step instructions for the user.

Where to download

Several tools providing all the necessary functions for making screen grabs can be used for free. For example:

• MWSnap (Windows)
• Wink (Windows, Linux)
• ScreenHunter (Windows)

How to capture an area using MWSnap

MWSnap uses a simple interface and should be familiar to anyone with Windows and Office applications.
When you start the program the main functions can be found on the left of the window which includes various options:

• Fixed rectangle - allows you to grab small areas of the desktop such as icons
• Any rect. area - allows you to select an area for grabbing by dragging a box over the area
• Windows/menu - allows you to automatically select and grab any window or menu on the desktop
• Full Desktop - grabs the whole desktop screen
• Repeat last - grabs the same desktop area as previously defined

How to store files

To store the grabs you require you can use the standard 'save as' option in the application's file menu to select the directory path.

How to add a graphics file to a Word document

Once you have saved your picture you can place the image into Word by using the "Insert/Picture/From File" option in Word's standard toolbar.

How to add a graphics file to a Wiki

Graphics to be added to a Wiki must be in the PNG format or a JPEG format. When saving a grab with MWSnap you have the option to select the picture format that you desire. Save it as a PNG in the 'save as' window.
Upload it to the wiki as you would a normal image..

Exercise 1 Adding a screen grab to a Wiki

1. Create a page
2. Grab a section of your desktop
3. Save the graphics file as a uniquely named .png/.jpg
4. Upload your file to wiki
5. Create a reference to the file on your page
6. Save the page

Help File Authoring

Help files may range from small, simple "read-me" files with very limited information to hypertext-based complete system documentation. Considering this, the most important aspect of a help file is accessibility of the information it contains. The most common reason for a user to look at a help file is to seek an answer to a specific question. In order to make this easy for them, it is important to reflect a while before starting to write.

First steps

• Identify topics
• Make a structure
• Make a design

Identify topics: Help files are designed to work in conjunction with other types of documentation. The differing types of documentation, including the help files, should work together to form a complete information package. A help file may not need to contain all of the technical details. It is the task of the developer or technical writers (or developer-technical writer team) to identify the topics for the help file. The best way to accomplish this goal is to analyze the product. Then, once you have identified all of the topics, separate them into related groups.

Make a structure: Once the topics have been identified, it's time to start structuring the help file. Keep in mind that the main purpose of the help file is accessibility. Although the structure may well depend on the software itself, there are some rules that are widespread and often applied. The content tree of the help file usually does not exceed 3 nesting levels. Often, 2 levels are used for small files that contain short chapters and sub-chapters, as is also the case with the help file. The help file doesn't need to have a narrative structure. It is not the manual, nor is it the guide book. Its main purpose is to provide quick access to specific information about the software. This goal is achieved by a simple content tree, and keywords that build the help file index.

Design: Design a structure that does not change often, even if specific information for a specific topic may change. This makes it possible to create a modular and flexible help file that can be used for the next version of the software. Keep in mind that HTML file names should remain stable. If the help maker tool allows it, it would be good to have a method of differentiating the various HTML files of the same name.

Making a Help File

• Access
• Content
• Hypertext
• Keywords
• Size

Access: make important information accessible in many ways. A help file is not a book that needs to be read in the order it is written. The introduction page may well never be read, while the other information may be searched for by index and accessed directly without using the content tree. If a specific topic is discussed in another part of the file, make a link that helps the user reach the related page directly.

Content: the most important part of a help file is its text content. Even if the graphics and formatting are attractive, the help file will be ineffective if the text content is limited.

Hypertext: if the information is standard-related, not specific software related, and the source is reliable, it may be useful to use hypertext to provide a link to content for those users who may be interested in knowing more about a specific topic. The most important rule is to use links where they really may be considered useful. However, it is probably better to use too little hypertext than too much.

Keywords: prepare a list of keywords that are related to the specific HTML pages that the help file consists of. Some users prefer browsing the content tree, but others go directly to the index and seek for the topic of interest by keyword. If the help file is comprehensive and the keyword list is well prepared, it saves a lot of time

Size: it does not make much sense to make a smaller file by limiting the information included in it. A help file should be a file that helps. It should contain everything that is needed to help the user operate the software and solve simple, typical problems. This means the size may vary from very small up to 15 MB and more.

Help Authoring Tools

There are a lot of Help Authoring Tools described in Wikipedia. Follow the link to read more about the tools.

Integrated collaborative systems - Content Management Systems

This section describes basic types of collaborating tools - CMS systems, wiki pages and so on.

XML-based

XML is a professional way to make a collaborative system with a single source. XML allows separation of source text and its appearance and layout.

Most of these systems are based on one of the following XML formats:

• DocBook
• DITA

DocBook was designed to contain documents such as books, manuals and the like. Documents in DocBook look like a Microsoft Word document; they are divided into sections, subsections, chapters and so on. A typical output format is PDF.

DITA was developed by IBM to contain information in small sections that are relatively independent of each other. Thus DITA is suitable for manuals, help pages, technical specifications and other documents. DITA is a relatively complex format that is universal for many industries.

DocBook is a more suitable tool for writing a novel, while DITA is more suitable for a set of help manuals. Typical output from a DITA system is HTML Help or PDF.

There are several other systems on the market that are based on proprietary formats. Those formats can sometimes better fit the actual needs of customers than the universal DocBook or DITA. As an example, the DocuManager format used in Schema ST4 falls in between DocBook and DITA. It is not too complex and enables production of strict topic-based documentation.

HTML based

There are lots of CMS systems on the market that use HTML as their source language.

CMS systems based on HTML are widely used in company web-sites.

Printable documentation production is not the primary purpose in most of them.

Wiki based

Wiki systems are based on special wiki-markup. This is simpler than HTML, so conversion to HTML is easy. (Of course - you are writing in wiki-markup but when saved, it is shown in HTML in your browser.)

Wiki based web-pages are not primarily intended for production of documentation. Wiki pages are mostly used in corporate web-pages, community web-pages or any web-pages that will be frequently edited manually.

PDF output of wiki pages is complicated since it requires conversion from HTML to PDF.

Revision control software

Revision control software allows a group of people to share the workplace.

It is a relatively simple CMS system that keeps versions of files inside a directory tree.

It is very useful for sharing documents inside a group. Every change is stored in the database and we can roll back to any previous version.

Revision control software must enable the following:

• Commits of new versions.
• Renaming, copying, moving and deleting files must retain the full revision history.
• Directories, renames and file metadata are versioned. Entire directory trees can be moved around and/or copied very quickly, and retain full revision history.
• Versioning of symbolic links.
• File locking for unmergeable files ("reserved checkouts").
• Branching.

There are many revision control software products on the market as listed on Wikipedia:

Open Source:

• Concurrent Versions System (CVS)
• Subversion (SVN) - CVS clone, better in some way.

Proprietary:

• Visual Studio Team System/Team Foundation Server, Microsoft
• IBM Rational ClearCase

Graphic editors

Raster graphics

Raster graphics, sometimes called bitmap graphics, is a basic graphics type. A picture is transformed into a group of pixels, and each pixel is saved individually.

If you enlarge a raster image, it will be pixelized and ugly. If you shrink a raster image, quality degradation is low.

There are plenty of raster graphics editors:

• Free: Windows Paint, The GIMP.
• Commercial: Adobe Photoshop, (Adobe Fireworks), Corel Painter ...

Raster graphics is great for photos and for screenshots.

Frequently used formats of raster graphics are:

• BMP - large files, not good for embedding into documents!
• JPEG - lossy format, great format for photos. Use quality setting between 70-92 for best performance.
• PNG - the best format for all screenshots! Loss-less format.

Vector graphics

An example is sometimes better than a ton of theory:

If you want to make a simple black line through a white picture in Windows Paint, what it actually does is create black pixels lying between two points. If you add text to your picture - you will darken the pixels where the text should be. Once done, you cannot simply go back.

A vector graphics editor will save the following information:

• a white picture
• a black line from point A to point B
• text "ABCDEF" in black Arial 12pt at position X/Y

Later, when you save your vector image as a raster image, the editor will paint your line and text for you as Windows Paint does!

You can later edit your graphics without needing to use the eraser.

The best feature of vector images is that you can resize them without ANY change in quality! (at least theoretically).

You can combine vector and raster graphics in a vector image but you will lose its great feature of free resizing.

There are plenty of vector/raster graphics editors on the market. Most of them combine both approaches.

• Commercial products: Adobe Illustrator, CorelDRAW, Adobe Freehand/Fireworks, Zoner Callisto, Microsoft Visio...
• Free and open source products: Inkscape is a good choice while it uses standardized SVG (Scalable Vector Graphics) format. Most graphic tools can import SVG and new versions of browsers (Firefox, Opera) can directly display vector graphics in SVG format (MS IE uses plugins such as Adobe SVG Viewer). So graphics created in Inkscape can be modified in other programs or even directly published on a web server.

Vector graphics are great for schemas, flow-charts, and most business and technical graphics

More info about vector graphics in Wikipedia.

Document Formats

Theory

When a technical writer is writing documentation, their work has to be saved to a file. There are several suitable formats for such a purpose.

From one point of view, the final document contains:

1. Text content - this is the text that the author actually writes.
2. Text appearance - this defines the size of the Header font, for example, font color, underlines, bold, etc.
3. Page layout - this describes exactly where the header is rendered, place/size of pictures, size of tables, size of page-borders, page-breaks.

If we want to produce a "proper" document for printing, the document has to contain all three elements.

If we want to view it on a monitor, only content and appearance are needed.

So if we simplify enough, there are three types of format we can save our work into:

• I. Containing text - text file
• II. Containing text + appearance - HTML, HTML Help, wiki, XML/DITA, XML/DocBook ...
• III. Containing text + appearance + layout - Doc, RTF, PDF, PS ...

If the author writes their work in a text file and wants their work to be printed, everything has to be set.

If the author wants to print work written in HTML, they have to set layout of the page.

If the author wants to print a Doc or PDF, they just print it.

Consequences

From this theory, there are interesting consequences:

Conversion from "layout" to "appearance" formats is easy. Conversion the other way around is not easy!

Doc --> HTML works.

Doc <-- HTML does not work fully.

Doc --> PDF works.

wiki --> PDF does not work fully.

HTML --> PDF does not work fully.

Doc <--> RTF works.

And so on...

Practice - Common Formats

CONTAINING APPEARANCE AND LAYOUT

PDF wiki

• The best format for professional presentation of information: most companies use it as the output format of their user documentation. The on-screen representation is almost identical to the version printed from the .pdf file.
• Easy to view: Adobe provides a free PDF viewer to everyone, and there are also a lot of free alternative PDF viewers.
• There are several free and commercial converters from most formats. For example, Adobe's own product Adobe Distiller converts almost anything to PDF.
• Not easy to convert from PDF to other formats.

Doc

• Most known format - MS Word.
• Relatively easy to convert into PDF.
• Very rich format, lots of things are allowed, too much for mass production, unfortunately.
• Not suitable for professional presentation of information - never the same rendering on multiple machines.
• Very suitable for authoring.

RTF wiki

• Functionally similar to Word Doc, Microsoft format.
• Standard for exchange between platforms, may be used in e-mails.

CONTAINING APPEARANCE ONLY

HTML wiki

• Format for WWW - very widespread format.
• Standard for presenting information, but not printable.
• Text based.

HTML Help wiki

• HTML based standard format.
• Used in "F1" help in applications.
• Largely used as output format of documentation.
• Standard for presenting information, but not printable.
• Compiled from a set of HTML pages.
• Not edited directly, after decompilation editable as HTML.

XML/DocBook wiki

• Standard of OASIS.
• Document oriented XML format
• Suitable for mass production - strict format.
• Content separated from appearance.

XML/DITA wiki

• Special format enabling database-like storing of information -Topic oriented XML format.
• Another standard of OASIS.
• Suitable for mass production - strict format.
• Content separated from appearance.

CONTAINING TEXT ONLY

Text

• Used in readme files for software.
• Several types of encoding to support national letters like ěščřžýď or cyrillic.

OTHER FORMATS

There are many other formats for production or processing of help and documentation: FlashHelp, Oracle Help, WinHelp, Adobe RoboHelp, Sun Java Help ...

Editors

For each format there are lots of editors. Some of them are listed below.

Doc/RTF

These formats are best opened in Microsoft Office Word. An open source alternative is the Writer component of the OpenOffice.org (OOo) suite.

HTML

• WYSIWYG editors - Adobe Dreamweaver, MS Word, MS Frontpage...
• Text based editors with support - jEdit, PSPad, emacs, ...
• Simple text editors - notepad, wordpad...
• More info on wiki.

PDF

Adobe Acrobat Professional and Adobe Illustrator allow making some changes to PDF files, but if the file you want to edit is available in another format, it is generally easier to edit that file and then convert it to PDF.

CHM

CHM or Compiled HTML Help is a popular and proprietary Microsoft format used for Windows desktop applications. Popular CHM generators or editors are

• HTML Workshop (free software)
• Adobe Robohelp
• WinCHM
• Doc to Help
• Help and Manual

back to Introduction to Technical Writing

back to Technical Writing Level 2