10 Software Documentation Best Practices

1. Perform documentation as required (e.g. %10 of total production time). No documentation is never a good solution as much as excessive documentation. It may include code documentation, requirement specifications, design documents, test documents, user manuals etc. Those documents are needed to be managed and shared also, by using version controlling tools and/or web based platforms.
2. Code documentation is important. Best way of doing this is producing self-documenting code. Variable, method, class, package etc. names must be meaningful and codeflow must be pure. For very complex code sections, short comment lines may be included. Javadoc-like standard entries are not required but may be added for auto document generation from code.
3. For the future developers, short and useful design documents may be prepared including key design features and UML diagrams. Practical user help documents may be useful also. These documents must not include unnecessary bulk info.
4. Requirements/issues/backlog item/function points tracking is important. For that operation, a tracking tool is more effective (it will have quick search, edit capabilities and a few more features) than writing them into a plain text file.
5. Test tracking is also important. Test scenarios and results may be tracked using tools (or with text files, which is not preferred) and associated with related requirements. By doing this, functional status of software may be monitored easily.
6. Documentation is a live process. If you produce some documents, it is a good practice to update or produce new version of those documents until the end of development process. If a document is not up-to-date, it is practically worthless.
7. For text file documents, versioning is important. For each new version of a document, a new version number (which is given with a stable versioning strategy) must be given. Also a version tracking table having change info may be included for better tracking.
8. Having a consistent document template is important for companies. Header, footer, headings, font sizes must be consistent in document and among other documents for better readability. It is also a good practice that having a cover page, table of content, table of pictures and a glossary for documents.
9. Document formatting, language usage and typing are other physical issues about documents and attention must be paid. Typing errors, unconsistent table sizes, indentations etc. will distract the reader.
10. Saving ‘lessons-learned’ info on a shared place is another good practice. Those items are some useful experiences (information or code/configuration sections etc.) about development process which may not be included in standard process documents. Lessons-learned info may give acceleration to the current developers or future developers about some challenging and repeating operations.

 
Reference: 10 Software Documentation Best Practices from our NCG partner Çağdaş Başaraner at the CodeBuild blog.