Documenting

What cannot be automated should be documented.

We use several ways to document a software system. They are Notes, Readme Files, Comments In Code and Git Commit Messages.

Readme Files

Readme file is a primary place where we put project related information. Details about dependencies, a guide to bringup a development environment, test and deployment procedures - all go there. Place Readme file in a root of a project. Some larger project software components may deserve their own Readme files. Use markdown for readability when you write it .

Notes

Every product we develop has a Notes document. Your manager shares the document with you when you start working on a project. At its minimum, it includes general information about a project, such as short description, repository url(s), contact points, etc. You are encouraged to add more information while you are working on a product. It can be FAQ, HOWTO or references to materials which you think can be useful during development.

Comments In Code

Comments in code is a great way to provide documentation in place. When you develop, ask yourself "If another guy reads this code, will he understand how it works?". In case your answer is 'No', open comment line and explain an idea behind your change.

Git Commit Messages

Git history exists as long as a project is alive. Use commit message to describe a problem your change is solving and what you are actually doing about it in technical detail. Copy-paste a crash backtrace there or provide a reference to a Stackoverflow post which helped you to fix an issue.