“The fundamental purpose of scientific discourse is not the mere presentation of information and thought but rather its actual communication. It does not matter how pleased an author might be to have converted all the right data into sentences and paragraphs; it matters only whether a large majority of the reading audience accurately perceives what the author had in mind.”
— George Gopen and Judith Swan (The Science of Scientific Writing)
1. Analyze the audience
Audience is the most important consideration in planning, writing, and reviewing a document. To write effective documentation that suits the users, we must understand their needs. There is no point creating a 200-page manual when a quick reference guide of 20 pages will do.
2. Use active voice, short sentences.
Use active voice in scientific and technical writing. Long and complicated sentences can cause readers to lose interest or to become confused.
Also, avoid use of jargon unless the reader is familiar with it. If we must abbreviate, we define the term in its first occurrence, and put abbreviations in parentheses. Example: Software Development Life Cycle (SDLC).
3. Use advance organizers.
Use bulleted list or a table of contents (TOC) to provide advance reference. Providing such information helps reader navigate back and forth between different, relevant topics.
Use cross-references to link related information that is described elsewhere in the document and is not essential to the current discussion. In online documentation, use adequate hyperlinks to cross-reference related information.
4. Balance text and other forms of content.
Use appropriate diagrams, pictures and tables to support the written text. Remember: A picture is worth more than a thousand words. 
Provide adequate white space. Too much text crammed onto a page intimidates readers and turns them away. In technical writing, we always use white space around the text to break up pages.
5. Choose the right format for distribution.
Different formats are available for storing and distributing technical guides to readers.
Most common forms are MS Word (.doc or .docx), PDF and HTML. Some prefer to use Microsoft Compiled HTML Help which is a Microsoft proprietary online help format. (It consists of a collection of HTML pages, an index and other navigation tools. The files are compressed and deployed in a binary format with the extension .chm, for Compiled HTML.)
Drawings can be in .vsd format. (VSD is a file extension for a vector graphics file format used by Microsoft Visio. VSD stands for ViSio Drawing. Microsoft Visio is vector-based software used to create diagrams and flowcharts. To view a VSD file without Visio installed, Microsoft provides the Visio Viewer.)
Other formats can used depending on reader’s convenience and preference. Example: certain embedded video files and powerpoint slideshows can be accessed by user anywhere using a web browser.
6. Review
Remember: Writing is a process.
Good writing doesn’t happen right away; it requires planning, drafting, rereading, revising, and editing. Learning and improvement requires self-review, peer-review, subject-matter expert feedback, and practice.
Inconsistency in technical writing affects credibility and the user’s perception of the matter at hand.
Before starting any technical writing project, Brandfocal Consulting (support@brandfocal.com) discusses the purpose, audience and format in which the documentation will be made available to the readers.
- Why Free Website Design Services Often Aren’t Worth It - November 29, 2024
- Choosing the Best WordPress SEO Plugin - November 28, 2024
- A Practical Guide to Local SEO - November 28, 2024