Chapter 10: Generating Documentation
High-quality code is not only well written, working, and tested—it is also thoroughly documented. Documentation allows us to share information that could otherwise get lost, draw a bigger picture, give context, reveal intent, and—finally—educate both external users and maintainers.
Do you remember the last time you joined a new project and got lost for hours in a maze of directories and files? This can be avoided. Truly excellent documentation will lead a complete newcomer to the exact line of code they're looking for in seconds. Sadly, the subject of missing documentation is often swept under the rug. No wonder—it takes a lot of skill and many of us aren't very good at it. On top of that, documentation and code can really part ways very quickly. Unless a strict update and review process is put in place, it's easy to forget that documentation needs work too.
Some teams (in the interest of time or...
