How do you write straight to the point documentation without looking sloppy and informal?

Question

I'm currently at a contract position and am looking to add to the documentation of the projects I worked on, to assist the next hiree taking over my projects.

The documentation I received was overly technical (i.e. references code right away, references replacing certain values on certain lines, no high level description at all)

How do I write documentation in simple plain English that is of actual benefit without looking sloppy? I find it difficult in areas such as outlining a system's flaws without coming off as judgmental, but still emphasize the severity of how detrimental some of the flaws are.

Answer 1

Q: How do I write documentation in simple plain English that is of actual benefit without looking sloppy?

Documentation should be created for the readers. Important elements include

• Content: The contents of the documentation should be aimed at the information the reader(s) need. Think about the types of tasks that readers will be using your documentation for. Make sure that the contents of your documentation are relevant to them, and provide all the necessary information. As you learn things about the system you are documenting, note items that took you longer than usual to understand, or that you feel are counter-intuitive. This is information that should be in the document as well.
• Organization and Cohesiveness: The contents of your document should be organized in a manner that is logical. For instance, to support task-based activities, the activities should be arranged in the order that the reader will be performing them. To document a system, provide introductions that give an overview of the system and how the major components / subsystems interact before going into details about how individual pieces work. If the organization has a wiki or similar Content Management System, consider using this for the documentation. If not, lobby to get such a system started, and get support from the team you are working with.
• Understandability: Only use terms that most of your readers will understand. Avoid jargon. If you do use it, provide your definition of the term. Define all acronyms and abbreviations when first used.
• Readability: Use correct grammar. An interested non-technical person should be able to understand the material.
• Context: As you have observed, detailed information that is not placed into a proper context can be difficult to understand. Provide introductory material that briefly identifies all the key components, layers, API, packages, etc. that comprise the system you are documenting.

Q: I find it difficult in areas such as outlining a system's flaws without coming off as judgmental, but still emphasize the severity of how detrimental some of the flaws are.

Practice egoless documentation. If there are awkward design elements in the system, you have a duty to highlight any extra information, care or steps a reader needs to know about, but do not judge the awkwardness itself. Avoid adjectives such as "idiotic". For instance, suppose there are several files that need to be changed in order to effect a simple configuration change. Do -- lay out the steps required. Don't -- waste text blaming the original designers for their lack of foresight and/or mental abilities.