Book: SE@Google Ch 10: Documentation

[gerhean]

Book: Software Engineering at Google
Chapter: 10- Documentation

Summary:

• Documentation is most successful when treated like code and incorporated into the traditional engineering workflow, and kept easy and simple.

  • This can be done by having internal policies or rules to be followed, placing it under source control, clearly establishing the owner of each piece of documentation, making it change with the code it documents, and undergo reviews and periodic evaluation.

• Documentation benefits the writer in the following ways:

  • It helps formulate an API. If it is hard to explain or define an API, it is probably not designed well enough.
  • It provides a road map for maintenance and a historical record. It helps the writer fix bugs in code they wrote some time ago.
  • It makes code look more professional and drive traffic. Other developers are more likely to use well documented code.
  • It will prompt fewer questions from other users. Less time wasted by writer to explain things.

• While documentation should be optimized for readers, one needs to be aware there are different types of readers which one might need to cater to, and write each documentation as broadly as possible.

  • In order to cater to the various audiences, it helps to:
    • Keep documentation consistent. This helps experts quickly find what they are looking for.
    • Provide very short overviews that explain the purpose of each section/piece of documentation. This helps novices avoid irrelevant code.
    • Separate user and developer documentations.