This document should be populated with project specific documentation. Be mindful with it and with your future colleagues that will join the project. As a general guideline:
- documentation should capture things that are not obvious from the code; reading code to understand what happens is more time consuming and error prone;
- separate clearly between interface documentation and implementation documentation: interface comments should describe the abstraction while implementation comments should capture the precise details;
- documentation and comments should generally be about what and why, not about how; keeping the majority of comments at a high level will avoid you the pain of having to constantly update them when the implementation changes;
- don't repeat the code: if the comments repeat the words used to name a certain variable/ method/ module then most likely the documentation is not complete;
- if certain code design decisions cannot be reflected in the code use this README.md file to clarify and document it; not only is it centralized but can also be easily accessed;