Contents |
Most people know instinctively what good documentation looks like, but would be hard pressed to say what it is that makes it effective. At the same time, anybody can spot bad documentation, and tell you in detail what's wrong with it- the content is poorly organized, it uses too much technical jargon, and it doesn't seem to cover the specific technical problem that the user is trying to fix.
Despite all of this, writing good documentation isn't as hard as you think. Most of it comes down to thinking of your audience as an actual person with real information needs, and tailoring your content to meet those needs.
This tutorial aims to provide a beginning set of guidelines for authors of technical documents for the Help site knowledge base. This document is part of a broader set of guidelines for creating technical documents using the Wiki.
For the most part, people don't read technical writing for fun- they're searching for a solution to an immediate problem, or perhaps to learn a bit more about how to use a piece of software or hardware. Your job as a technical writer is to anticipate their needs and give them answers as clearly and effectively as possible.
One of the first decisions you should make when starting a new document is what exactly you are writing about. Define the use case for this information- what has happened to bring the reader here and what do they need to learn from your document?
Often, the title of a document goes a long way toward summarizing its purpose. Take a moment to write down a few possible titles for your document. Is the title in the form of a question? Is it focused on the fine details of a problem? You might be looking at creating a Solution document, or perhaps a FAQ.
Next try writing a quick summary of the document, using no more than a few sentences. Did this summary touch on all the major points you want to cover in your document? What's missing? With some revision, this abstract should serve to tell your readers everything they need to know about your document in a nutshell.
Now think about your audience, the people who you imagine will actually be reading your document. Try to imagine them sitting in front of you, with questions in hand. Who are they- students? Faculty? Are your intended readers completely new to this subject, or are they advanced users?
Once you have a realistic sense of your audience, tailor your content to fit their needs. For example, how much time do you expect your readers to spend on your document? Perhaps you should be brief. On the other hand, maybe your readers are looking for a lengthier Tutorial on the subject. What is the problem they're trying to fix, and how much information do they need to fix it?
What kind of computer do your readers use- are they using laptops? Are they running the Apple Operating System, or maybe Linux? What do they usually do on the computer, and how is the related to your subject?
Once you've determined the purpose and audience for your document, you should clearly state that information in the introduction. Telling your readers up front what you're writing about and for whom it is intended lets them quickly decide if your document is for them.
At this point, take a moment to think about the assumptions you've made while identifying your purpose and audience. You should have a sense of who your readers are, and what level of expertise they have. These are assumptions, which you should state clearly at the beginning of your document.
For example, someone writing a document about creating web pages might assume that the audience is already familiar with the basic concepts (writing with HTML markup, using file-transfer programs, etc.) and jargon (cascading style sheets, relative and absolute links, etc.). If instead this document was intended for beginners, the assumption should be that the readers won't understand these concepts, so they would need to be explained as they are introduced.
Before you start committing your thoughts to writing, take a moment to look at other related documents on the Help site. Imagine the search terms or categories your audience might use to find your document, and use those methods to see if other documents already cover the subject. If your information is available in another document, or from somewhere else on the web, think about how to frame your content in a unique way, and reference the other documents.
With this groundwork laid, it's time to start organizing your content - the actual explanations and instructions of your technical document. This is where structure comes in.
All documents should have clear and consistent structure, starting with an introduction or overview and closing with a summary that provides references for additional information. This consistency makes it possible for experienced readers to know what to expect, and allows them to focus on the content rather than the delivery of the information.
Because many documents follow a similar structure, we've constructed models- called Genres- to make it simple to structure such documents.
Start your document with an introduction or an overview, where you tell the reader the purpose of the document and your assumptions. In addition, the introduction can tell the users what they can expect to learn from the document by the end.
Break your content up into logical sections, and arrange them according to the type of document you're writing. Sections can include sub-sections (and sub-sub-sections) where it helps to organize the content. In general, sub-sections shouldn't be used for only one chunk of information; if there aren't at least two sub-sections, the content should just be incorporated into the parent section instead, perhaps as a note.
Some information, such as detailed instructions or lists of equipment, are best organized as structured lists. This can include either sequential lists (using numbers instead of bullets) or itemized list. Sequential lists are used for sets of content where the order matters; i.e. step one must be completed before step two, etc. Itemized lists should be used for lists where the order doesn't matter (a list of available software, for example). Like sub-sections, lists should never be used for only one item.
As a rule of thumb, your document should be as brief as possible, while still communicating the essential information to your readers. In general, users won't have the patience for a long document- they've got work to do, and they don't have time for long explanations. Keep your text punchy and on-topic to keep their interest.
If you tend to be verbose (like me), plan on going back through your text a few times at the end and cutting it down to size. Alternately, if you find that you tend to write a lot of lists and sentence fragments, take a moment after the first draft and go back through your text. Flesh out the short phrases into complete sentences (including punctuation) wherever possible. Find a happy medium between writing choppy, incomplete phrases and writing novel-like paragraphs of explanations. Ideally, you want to get your ideas across clearly, and without making it look rushed or incomplete.
Titles for the document and sections should be clear and descriptive, without being verbose; Punctuation should be avoided in titles generally, but exclamation and question marks can be used as appropriate. Titles should be Title Case (capitalizing the first letter of each significant word).
For KMT "Quick Answer" Document types, the title is typically a question and the content is the answer. For this reason, the title should be phrased as a question, including a question mark.
As you write this document and others, strive to define a distinct, friendly voice. After all, you're trying to help your reader understand the subject, not confuse or frustrate them further.
To this end, write using short, clear sentences. Keep your writing focused on the subject at hand, and be as concise and direct as possible. Focus on easily-understood writing, even if the audience or content is technically advanced. Unless there is a strong reason to do otherwise, write in the present tense and avoid weak sentence constructions.
As you attempt to explain new technologies or ideas to readers, it is often useful to use analogies and metaphors that are relevant to your audience. The metaphor gives the reader a mental model, on which the rest of your explanation can be based.
If you're writing for relative beginners in a subject, compare the subject to something else from their experience- for example, "Email spam is like junk mail" or "MyUNC is like a gateway". If on the other hand you're writing for more advanced readers, or for a subject that is similar to other products, your analogies can be more obscure- "Second Life is like a MUD with graphics instead of just text" , or "Firefox is a web browser like Internet Explorer, except that it's open-source software and can be extended with add-on functions."