Technical Writing Tools

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:

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.

"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 just glance 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."

"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."

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:

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:

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: 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: 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.

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 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:

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

Open Source:

Proprietary:

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:

Raster graphics is great for photos and for screenshots.

Frequently used formats of raster graphics are:

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:

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.

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:

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
Doc
RTF

CONTAINING APPEARANCE ONLY

HTML
HTML Help
XML/DocBook
XML/DITA

CONTAINING TEXT ONLY

Text

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
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