Cristian Scorohodco

Introduction

Documentation is the critical part of the software development projects that supports all the steps starting with the initiation and planning and ending with the user acceptance testing, project launch and post-implementation support.

Knowledge transfer, transparency, ease of use, support & enhancement, and even total ownership cost heavily depend on the documentation's quality and structure. This post includes some valuable guidelines for writing good documentation.

Guidelines for good documentation

Corporate Styleguide

Follow the corporate style guide to develop professional-looking documents. A common styling convention cal allows you to structure the info in a more predictable and unified way. Applying a common style guide for your documents will always remind you about the necessary conventions to follow.

Cover page

Always have a beautifully designed cover page that includes just enough information. The cover page is the “face” of the document; therefore, it must be clean, well-structured and communicate the information about the document. A good cover page should include the document name, version, last updated date, project name, company data.

Table of contents

A table of contents is a mandatory part of the document, which is necessary to provide the reader with a short and concise presentation on what’s included in the document. Always have an auto-generated table of contents in the document and ensure that critical chapters and sections are included.

Executive summary

An executive summary is an absolute must that needs to be contained in the documentation. It should provide an overview of the document, as well as include the scope and purpose of the document. It should be short and concise to be read and understood within 1–2 minutes. A good executive summary typically can be limited to 3–5 sentences.

Glossary

The glossary is necessary in cases if your document includes multiple subject-matter abbreviations, acronyms and definitions. Always remember about the document’s target audience and have specific terms in a glossary to improve the document's readability.

Acknowledgements and conventions

A chapter dedicated to acknowledgements and conventions is helpful if your document includes multiple formatting options aimed to serve various purposes, i.e. attract user attention, highlight an extremely important piece of information or specify that the part of the document is not finished. If you widely use various types of formatting (i.e. bold, highlight, italic, code snippet, etc.), such a chapter will improve the understanding of the document by the audience.

Versioning and revisions

Versioning and revisions log is necessary to reflect the evolution of the document contents. It should be used when the document has a long period of life and when multiple authors edit it. In addition to the version and revisions log, it is beneficial to enable tracking of changes when editing the document.

Headers & footers

Structured headers and footers are an absolute must of the professional document. These can include various helpful information, but usually, to improve readability, it’s suggested to have the document name, document version, last updated date and page numbers in the header and footer of each page except the cover page and table of contents.

Figures, images and captions

In multiple cases, documents include figures and images, besides text info. When embedding media content in the document, always remember the following guidelines: media should be visible and print-ready (i.e. have a good resolution), should be editable in digital versions of the documents and always include captions that reflect the description of the media content.

Headings & chapters

A clear structure of its headings always defines a well-structured document. Use the power of headings to define document chapters and sections clearly. To improve readability prefer using numbered headings for chapters, sub-chapters and sections.

Paragraphs and text content

To capture the reader’s attention, focus the reader on the document content and make sure that the information is delivered most efficiently, the text should be structured in clearly delimited paragraphs. Paragraphs should not contain more than ten lines of text to avoid the document becoming hard to read.

Document protection

If the document includes confidential, corporate, private, intellectual property or secret data, always apply protection to the document contents. Security can be enabled using copyright notice and privacy policy described in the document by applying watermarks and editing or viewing restrictions to the document (ex., password protection and encryption). Some good examples of such document protection mechanisms can be found on the Internet.

External references

Consolidate and represent the list of external references separately if you use some external data sources co-related to the current document. Having all the external references in one place would significantly improve the comfort of the document’s audience.

Appendixes list

If the document has some appendixes, always list them in a separate document section. Enumerate appendixes using headings to reflect them in the table of contents. Along with the appendix name, always provide a short description of its relation to the current document and an overview of what’s included in the appendix.

Conclusions and endnotes

One of the criteria of a well-structured document is the ability to represent the conclusions and endnotes based on its contents. Include conclusions and endnotes when necessary to reflect the final thoughts and outcomes created by the information included in the document. Best suitable for executive-level reports, user manuals and scientific documentation.

Final thoughts

Writing good documentation is challenging and can be compared to craftsmanship, but it is a critical phase of the knowledge sharing and transfer process. Well-structured and organised documentation is a crucial element of learning, information exchange, and collaboration that leads to project and business success.