Technical writing 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.

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

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

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.

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

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

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.

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.

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.

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.

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.

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.

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

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.

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.