Over a million developers have joined DZone.

10 Software Documentation Best Practices

DZone's Guide to

10 Software Documentation Best Practices

· Agile Zone
Free Resource

Learn more about how DevOps teams must adopt a more agile development process, working in parallel instead of waiting on other teams to finish their components or for resources to become available, brought to you in partnership with CA Technologies.

  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.

Discover the warning signs of DevOps Dysfunction and learn how to get back on the right track, brought to you in partnership with CA Technologies.

java ,documentation ,tips and tricks ,tools & methods

Published at DZone with permission of Cagdas Basaraner, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}