Joseph D. Chapline was the first technical writer to introduce software documentation to the rest of the world. Back in the year 1940, he worked for Eckert and Mauchley and was the first technical writer employed to document the way an operating system worked. The first user guide he wrote was Binac Computer User Guide.
Sun Microsystems' Java programming language was first used in a device that brewed coffee.
This is the first ever blog on technical writing in Pakistan.
After you've prepared your document outline, it's time to develop the document prototype.
Why create prototypes? There are three main reasons for creating prototypes:
1 - It helps test the page layout, design, headings etc. Also, if you need to revise the document structure, you can identify it early in the process by prototyping. 2 - You can show users, colleagues and Senior Management the prototype and ensure that the manual meets their needs. This step also helps to get management 'buy-in' and sign-off. 3 - It's easier to start writing, as the prototype serves as a document blueprint.
Tips for creating prototypes? When you preparing the prototype, keep in mind the following:
Use the active voice: This makes the writing easier to follow. With the active voice, the subject of the sentence performs the action of the verb. For example, "You can visit the page by clicking this link." The passive voice often takes more words than the active voice and can create ambiguity.
Use the term "you" for the user: When you do this, the documentation seems more friendly and approachable.
Write your steps as numbered lists: Indent the numbered lists to make them stand out from the rest of the text.
Use command verbs: When writing steps, ensure that they follow the correct sequence.
Choose words carefully: Define new terms in a glossary. Use simple words whenever possible. Avoid technical terms and jargon that are not required.
Be concise: Use the least possible words to explain concepts, especially when writing steps in processes and procedures.
Be consistent: When you use a specific term to refer to a function, continue to use it throughout the publication. Don’t change the terms for the sake of variety. This will only confuse the user!
Highlight critical information: Use bold type for warnings and critical information, or place a symbol next to the text for emphasis.
If you use tables or screenshots, include them in the prototype. Your reviewers will then have a more reliable document sample.
Many documentation departments face the challenge of managing hundreds of files with many writers working on them at the same time. For a Documentation Manager, there are several options available to remedy this; most involve either Microsoft SourceSafe, CVS or PVCS to manage this thorny process.
Lack of Guidelines: When it comes to version control procedures, the lack of formal guidelines is a serious issue for Publication departments; For example, there may be no "best practice" guidelines for "getting" versus "checking out" documents. With certain software packages you can "get" a copy of a file in read-only mode and then make it write-able. This overrides the security "check out" feature of the system which can later prove counter-productive and create even more confusion.
Checking Out: Checkout procedures have several purposes: 1. They put a copy of the file on a local machine. 2. They lock the file; only the user who checked it out can check it back in. This process protects your team from itself — it alerts the rest of the team when someone is working on that file. Version control software protects team members when two or more writers attempt to update a document simultaneously. Should this happen, they risk losing one writer's contribution, as the last saved version will overwrite the previous version.
Using CVS: CVS doesn't truly support a lock system. Instead, its default mode is a 'merging model'. You can use a lock system with CVS if you use the -L and -l options to the Admin command.Multiple users can check out the same documents and then attempt to check them back in. When working in ASCII modes, such as HTML, this works fine as it will calculate your differences from the last version and apply them. Depending on your product version and platform, it can figure this out quite well.
However, if there is a conflict it will stop you checking files back in, and force you to manually reconcile the difference.
RCS and Microsoft SourceSafe offer locking.
Note: You can override the checkout lock, but use this in emergency situations only, e.g. when someone leaves the company and forgets to unlock their files.
When you override a lock, ensure that the locker has checked in the most recent version, or you'll lose the work.
Managing versions by product line:
When preparing documentation plans, one approach is to delineate your documents based on product lines and give each writer their own set of files to manage. You then have to ensure that there are no files shared between products.If you don't control this, you will end up with writers working on the same files, and everyone having copies of the files on their local drives to edit. Documents will clash when they are checked back in.Needless to say, the larger the team, the more important a clearly defined source control procedure is followed.
Everyone would prefer reading a technical document that is visually appealing rather than one that is cluttered with dense copy and little or no white space. Simply put, white space is blank space on the paper. It can be used for various techniques as well as an easy way to enhance your document's appearance.
- White space can be used to achieve the following results: - Frame the content - Separate ideas - Define sections of your document - Provide relief from copy - Highlight information
White space simultaneously "opens up" the document and segregates information into manageable segments. Your readers can only digest so much information at one time. Think of white space as you would a five-course meal served in a four-star restaurant. Served in distinct courses, the food's visual impact is much greater than that of a crowded buffet table, which is laden with as much food as possible in as little space as possible.
You can achieve white space in the following ways:
- Before and after headings - Wide margins on all four sides - The space between columns of words or numbers - Unjustified right margins - Indented sentences - Between paragraphs - Bulleted items in a list
You may already be incorporating these techniques in your technical documents; however, if you are not, experiment with the ones you are not currently using. To see the difference between a document that appears crowded and dense with text and one that is open and visually appealing, compare a document that you have already written with the same document after you have enhanced it with white space. The difference will astound you-and please your readers.
Using Emphasis Techniques
You can use four different techniques to emphasize material in technical documents. The four most commonly used are the following:
The following typographical techniques are easy to incorporate into a technical document:
- Bolding - Italicizing - Underlining - USING ALL CAPITAL LETTERS - {Putting words in brackets} - "Using quotation marks"
Bolding is an effective way to separate headings from the text of a document. When used sparingly, bolding can be a dramatic method of highlighting important information.
In the same way, italicizing can draw your reader's eye toward words that need special notation. Technical writers use italics to differentiate subheadings from headings, to distinguish technical words and phrases that will be defined later, and to set apart material that is quoted from another source.
Underlining is used sparingly because it is often hard to distinguish letters that have descenders when underlined. For example, words that contain the following letters run the risk of being obscured: j, p, q, y. Note these same letter when they are underlined: j, p, q, y. Using all capital letters works well for short headings and words that need special emphasis; however, studies have shown that text using all capital letters is much harder to read than what is called "mixed case." Compare the following two headings:
USING GRAPHICS IN TECHNICAL DOCUMENTS Using Graphics in Technical Documents
Brackets are an effective way to separate parenthetical text; however, bracketed information appears to be an afterthought. If it is important, it should be given equal status to the information that precedes or follows it. Often, the busy reader will skip information that is bracketed, assuming that it is an afterthought or secondary in nature.
Quotation marks have been almost entirely replaced by italics. However, when you wish to give special meaning to a word or phrase, quotation marks will highlight the words. Also, a direct quote may appear within quoted information. In that instance, quotation marks indicate that a person or source is being quoted verbatim.
Graphical Techniques
Graphical techniques include framing, shading, and coloring. These techniques often do not reproduce well when multiple copies are made. Shades of gray can easily become too dark to read or too light to be effective. In a technical report, a chart may be framed, shaded, or colored to make it stand out from the regular text. Using colors for pie charts and bar graphs is especially effective. Unfortunately, the cost of color is often prohibitive. If the document is written for in-house distribution, the variations of gray can separate bars or slices of the pie. Again, it is important to determine if the shadings reproduce well.
Spatial Techniques
Spatial techniques include the use of white space and consistent placement of information. An example of this would be to always place the name of the procedure at the top of the page, the page number centered at the bottom of the page, headings centered, and subheadings flush left. By being consistent with such information, your reader knows exactly where to look for what they need.
Verbal Techniques
Verbal techniques include using the same words as identifying terms such as Important, NOTE, or Caution! When you write procedures, certain words tell the users what conditions must be met before they can go on to the next step. Words such as NOT are much more recognizable than words that start with a negative prefix such as in or un.
Compare the following two conditional statements:
If water levels are NOT adequate,Then adjust the flow valve. If water levels are inadequate,Then adjust the flow valve.
Technicians are trained to focus on verbal techniques such as NOT. Recognizing what to do-or in this case, what not to do-in the field can literally mean the difference between a safe working environment and one that is potentially fatal.
Technical documents are technical in nature. They lack the sexy, "cool" appearance of a glossy magazine or a best-selling novel. Even so, there is no reason why a technical document has to be cluttered, dense with copy, and uninteresting. By considering the appearance of your document and using visual enhancements, your work may stand out as the model of what all other documents should look like in your company or your field. You may not have begun your technical career with dreams of writing technical documents, but as your work is continually praised and held as a standard, you will feel a great sense of accomplishment.
Ideally, software and its documentation will be localised (translated) into the languages used in the target markets. However, in many cases, it's not cost-effective do this. Even if the target markets are the English-speaking countries, there are differences between the way English is used in the USA, Britain and Australia for example, and it's easy to cause confusion. This article examines a few issues. Most readers will have no problem whether they see "dialog box" or "dialogue box" (assuming that they know what one is in the first place!). However, is "12/1/1999" the 12th January or 1st December? If your software is for an international market, then it makes sense to avoid ambiguities caused by differences in language usage.
Then consider readers who are not native English speakers. Many verbs in English consist of two or three words. Often, they can be separated by a noun. These phrasal and prepositional verbs (which typically are of Anglo-Saxon origin) can sometimes be a problem for people whose first language is not English; equivalent verbs which are often derived from Latin and Greek roots are often more easily understood. Here are a few examples of problematic verbs and their alternatives:
Don't use: bring up (a menu) Use: obtain
Dont' use: end up with (a result) Use: results in
Don't Use: fill out (a form) Use: complete
Don't Use: put off (a decision) Use:delay
Don't Use: turn up (the volume) Use: increase
There is a counter-argument that says non-technical users (who are native English speakers) may feel more comfortable with words of Anglo-Saxon origin, because they are the words of everyday speech.
Finally (and not seriously!), if users break their keyboards after you've instructed them to "hit the Enter key" when you mean "press", who is to blame?
Pakistani Technical Writers on the Web ... sharing news, rumours, trends, articles, tools, resources, opinions, links and other stuff on technical writing
