Home » Writing & Publishing » Technical Writing » Tips for Technical Writers

Tips for Technical Writers

© Jeff Hanvey

1. Begin by getting familiar with your corporate style. If there is no existing style guide, either review existing manuals to determine what has been done in the past ( Pay special attention to the language, assumed prior knowledge, general organization and presentation of how-tos (task-based or informational)) or choose a style guide.

2. Start planning your project.
(a) What is the final publication date?
(b) How long does it take to acually publish the manual? (this will give you a completion date).
(c) What are the critical dates? If you're documenting a product, what are the critical dates for that product? For example, the product may go into beta testing on Sept 1, meaning that is the date by which the development team wants basic instructions.
(d) Build in at least a week for technical reviews.

3. Define the scope of the manual.
(a) Determine who the audience for the manual is. Is it for a select, advanced user base? The general public? What is their level of education? Age? Gender? Technical knowledge?
(b) Based on (a), what topics must you cover? Is there a need for a short tutorial? Basic information?
(c) Based on (a), determine if the steps covered should be task-based (usually good for beginners), informational (just listing the steps for reference), or a combination of both (usually the best way to go).
(d) Decide what level the language should be. Watch out for jargon and very large words.

4. Determine how the material is going to be organized, based on how the audience will use the manual (this also affects what the final product will actually be: online help, a manual, et cetera). Generally speaking, how-to's move from basic features to more advanced processes.
(a) Is it part of an on-screen help system? For example, on-screen help topics are usually descrete steps based on using a specific feature.
(b) Paper manuals usually can discuss systems rather than tasks - the on-screen help topics are put together to explain how-to's like building a document, for example.

5. Start gathering information.
(a) Interview subject matter experts
(b) Find existing documentation (never, never redo things that already exist).
(c) Research using all resources: web, print, whatever.

6. Develop a "working outline," divide the work into chunks, set deadlines for the completion and review of each chunk (or draft). If possible, include a "freeze date" after which there will be no more reviews.

The copyright of the article Tips for Technical Writers in Technical Writing is owned by Jeff Hanvey. Permission to republish Tips for Technical Writers in print or online must be granted by the author in writing.