Documentation lab
No one denies that documentation makes a huge difference; yet many people don't RTFM. A scientific experiment conducted by the [redacted] concluded that there are two primary explanations for this phenomenon:
- Some people say they would love to, but there was no FM to FR.
- Others have developed a condition called gramophobia (from the language of ancient geeks it means "fear of letters"). It is a trauma caused by exposure to manuals written by ex-employees of companies that manufacture vacuum cleaners. It turns out that these employees got so good at creating things that suck, that documentation written by them inherits this feature.
This assignment is about saving humanity by learning to produce documentation that rocks.
Contents
Objectives
There are several paths to choose from, each of them is focused on a different target audience:
- ordinary people - end users who run your program. This is a high-level guide that explains how to use the product (installation, removal, updates, using the features, etc.).
- extraordinary people - your readers will be programmers who rely on your API to build their own software, or those who end up maintaining your system.
Your mission is to create such a document; the choice can be based on personal preferences or the nature of your course-work assignment.
Notes:
- You are not obliged to produce all the content. It is sufficient to define the styles and verify that the mechanism works by producing some sample documents filled with "Lorem ipsum" text.
- The document must be easy to read:
- The text should not be convoluted, keep things simple;
- The overall appearance of the document should be attractive. Although beauty is a subjective matter, try your best to produce something people will enjoy reading.
- Feel free to deviate from the requirements, if you think it is of reason to do so (you'll have to explain your rationale).
Recommended tools
If you're not sure how to get started, have a look at these recommendations; they're divided into several categories. Note that at times the lines between them are quite blurry. There's nothing that prevents you from using DocBook for writing everything (including API documentation), and there may be plugins for MediaWiki that convert the entire wiki into a printable PDF.
Feel free to rely on common sense and choose an instrument that is appropriate for your environment.
- For API documentation - usually generated from comments present inside the code itself
- For user manuals
- Something that may be applicable in either case
Requirements
Generic
- Content must be separated from style information; one must be able to re-generate the documentation in a different style with a minimal effort.
- Hyperlinks must be present - one can click on a reference and the document will be switched to the target of the reference.
- The document must:
- be searchable;
- have a table of contents;
- be produced in at least 2 different formats, for example: PDF and HTML.
Manual
These requirements are for the manuals written for end users. Here's what you should keep in mind:
- Such manuals will be viewed on the screen, but they can also be printed.
- Non tech-savvy readers will be a part of the audience.
Therefore these recommendations apply:
- Prepare a special style for the following types of text:
- Names of menu items
- Button labels (see the examples section)
- Info-boxes:
- Warning
- Tip
- Images and screenshots must be indexed, so you can refer to them throughout the text
API reference
- Generate an index of functions, classes and macros.
- Syntax highlighting.
- Include source code snippets or a helloworldian program to illustrate how the functions should be called to produce useful data.
Constraints
- The assignment must be implemented using freely available tools and rely on open document formats.
- Using Microsoft Word or other commercial closed-source software is not allowed.
- The document must be generated, rather than be the product of "hard coded" instructions. For example, if you add a new function to the API or add a new screenshot to the manual - the index will be updated automagically.
References
- How to write text that is easy to understand
- How to get developers to document (Slashdot discussion)
- Novell documentation style guidelines
- openSUSE documentation (source code is provided as well)
Examples
- Opera's documentation uses a special style for rendering names of keys, which makes it easier to understand when the manual refers to a button you press on the keyboard (vs buttons rendered on the screen).
- Infoboxes used in Fedora documentation