Documenting WordPad
|
Next >
|
|
This is the first article in a series of nine describing the work involved in developing a user guide for WordPad.
|
1. Concept
I have for some time had in mind to write a user guide for WordPad to be used as part of my tech writing portfolio. And in connection with the recent launch of this web site, I got the idea of writing an article series describing the work from beginning to end.
The idea of documenting WordPad has already been conceived and done by others. My writing of a user guide is therefore not supposed to replace any existing documentation. At the same time I have to say that I cannot be made responsible for any loss of data caused by following what guidelines and procedures I write in the guide. In other words; view this project as a look behind the scene and as an example of what technical writing can involve.
The outline for the article series and a few initial thoughts are
- Concept - This document
- Outline - I am not one of those super outliners that begin in the top left corner on a blank sheet of paper and when reaching the bottom right have produced a complete and no-editing-required outline. Instead I write the outline as early as possible and use the time it takes to go through the other tasks to make refinements.
- Format - I have already chosen PDF as the format for final publication. This is available to most people and enables both on-line viewing and downloading. It requires only the free Acrobat Reader program from Adobe.
Publishing in HTML-format is saved for later - perhaps in a separate article series.
- Template Development - In extension of the format is the development of a template. I have decided to begin from square one and that I will not re-use anything. To make the guide easy to print I have decided to make the page the height of a Letter-sized sheet and the width of an A4-sized sheet.
I expect the building of the book or set of files that will make up the source files to be more or less simple leg work.
- Research and Writing - These two are closely tied together, which means that I will document and test functionality concurrently. Changes to the initial outline are also likely to occur during this task.
- Index - The value of a good index is highly underestimated. Some people view indexing almost as a form of art and several books are available on the subject. In my own experience it is best to realize from the beginning that it is next to impossible to create index entries for all the subjects readers may look for. Going through the document systematically and placing index entries at every key section is a good place to begin. Refining the index with additional cross-references and some to-be-expected entries normally does the rest.
- Review and Editing - Reviewing my own work may be the toughest task of them all, as I risk getting myopic. On the other hand; putting the work aside for a day or two is usually enough to gain a new perspective.
Editing is far easier to deal with - just edit the changes found during the review. Sometimes this entails varying degrees of re-writing, which then triggers new review cycles.
- Publication - If the document is set up properly and test publications have been produced throughout the entire process, then this should be just like pressing a button.
- Evaluation - My experiences with creating the guide and writing the article series.
After the completion of each task I will write an article with the experiences gathered during the work.
Time is an issue. As I have a daytime job to attend to I cannot pull entire days or weeks out of the calendar for the project. The work will be done in my spare-time.
