Sunday, July 27, 2014

Technical Documentation - The beauty of one-page documents

A lot of companies with technical teams do not invest into hiring technical writers. The job of great technical writers in under-estimated, but it all comes down to hiring one more software developer over a technical writer. If there were an easy way to quantify the value of great technical documentation, then more investment would be placed into this area.

Then it comes down to the existing team of software developers to write the documentation for the team. There are two types of technical documentations:

  1. Project documentation needed to benefit the technical and business team on the project and to pass all the audits
  2. Living documents (current state docs) that get updated to represent the current state of your systems

The project documentation is typically done because it is part of PDLC and it needs to be done to pass the audits. On the other hand, the technical team is not religious about the living documents because you have place extra effort and explicitly allocate time for it outside the project work. If you include it into the project itself then it affects the budget of that project.

The IT land is a fast-paced environment and we have to make compromises. At the end of the day, my recommendation would be to write one-page documents for different areas of your systems. One-page documents with diagrams give you enough information about the system to get rolling and the rest is up to you and technical abilities to dissect the code and figure out the rest; if you have clean code then the code itself is a piece of documentation. Even if you write longer documents, most of the people are not going to spend time reading them.

Therefore, take 5-10 minutes here and there and convert those unpolished notes and put together quick one-page documents with diagrams. Then one person on the team can take charge and create a sitemap of all these documents.

- -

#tech #documents #technicalwriter #programming #coding #softwareengineering #PDLC #SDLC #almirsCorner

No comments:

Post a Comment