Part 1: Let’s Write Technical Documentation, said no one ever…

 

Purpose of Software Documentation

Requirements: Identify what is being built and verify stakeholders’ expectations are being met.

Design / Architecture: Define how the system will be constructed, describing how critical components fit together.

Code / Technical: Enable task completion and understanding.

Test Plans / Test Cases: Define the approach to testing; expose errors or demonstrate correct behavior.

End – User: Enable task completion; provide support and troubleshooting.

 

Plan and Research

What is the purpose of the document?

• If the document doesn’t have a purpose it shouldn’t exist

Analyze your audience

• Who will be reading this?

What do they already know?

• Why are they going to be reading it?
• In what environment will they be reading it?
• What is their state of mind?
• What do they NEED to know?

 

The Writing Process

1. Organize your content and ideas — simple to complex, chronological, specific to general

• Create your writing plan by making lists or categories. If you find any that don’t directly relate to the purpose, take them out. Think about your writing format. Will you be using bulleted lists, graphics, charts or is there a style guide you need to be following?

 

2. Write the first draft

• Write. Follow your plan from step one. Don’t worry too much about grammar, formatting, word choice, spelling, or those types of things.

 

3. Review and revise

• Does it fulfill its purpose?
• Is there anything missing?
• Is there anything that can be omitted?
• What questions will the reader have?
• Is the writing easy to understand?

 

Launch

• Handle translations with languages
• Bundle up all the deliverables for the client (e.g. READMEs, web pages, PDFs, etc)
• Coordinate with the developers and other writers on the project
• Create a plan to update the documentation (i.e. bug fixes, new releases)

 

Writing tips and best practices

Accuracy in writing

 

Document Accuracy

• Contains proper coverage of topics in appropriate detail
• Focuses clearly on the problem or solution
• Solves theoretical or practical problem

 

Stylistic Accuracy

• Words are used precisely to express meaning
• Sentence and paragraph structure analyze topics effectively

 

Technical Accuracy

• Technically accurate understanding and representation of the subject
• Depends on the writers knowledge of subject (research is VERY important)

 

Clarity

 

Structural Clarity

• Introduction, table of contents
• Visual representations
• Descriptive headings

 

Stylistic Clarity

• Say what you mean

 

Contextual Clarity

• Put it in context, What is the big picture?
• State the purpose
• Precede the document
• How does the document relate to other documents?

 

Conciseness

• Convey only the needed material
• Have a clear focus
• Use visuals rather than words
• Eliminate non-related words

 

Tone

• Be conversational in your writing, write the way you talk
• Be personable, show your personality

 

Tense

• Verb forms
• Mostly use present tense or future tense
• Keep the same verb tense throughout the document

 

Typography Guidelines

• Communication and clarity are most important
• Keep contrast high
• Limit the number of fonts
• On the web, use web-safe fonts
• Use size 10 or larger
• Use ALL CAPS Sparingly
• Design for copy-and-paste

 

Technical documentation is not the most exciting task, but a necessary one, since projects with incomplete, poorly written or no instructions can be frustrating . Hopefully these tips will help you write technical documentation with less stress and more confidence. Stay tuned for Part 2!