Documentation can be super valuable for an organization. It can enable people who don't know how to handle a particular piece of work to learn how to do it and manage it.
But it's also hard to define what's good documentation and what's terrible documentation. Here are some examples of what I consider helpful documentation:
- the ones where readers can easily contribute (wikis or git repositories that are open to submitting pull requests)
- the ones that have a FAQ section with common questions
- the ones that you can find by doing a keyword search
- the ones that provide code examples that you can edit and run on the browser
- the ones that mix text and video
- the ones that split long videos into smaller ones, or the ones that have a long video with a full transcript
- the one that's more or less up-to-date
Documentation can significantly decrease the cognitive load in teams by helping them find the information they need to perform their tasks without depending on other teams/people. Another benefit to documenting is that the person getting help gets it immediately and does not have to wait for the other team to help them.
Follow me on Twitter or subscribe to the newsletter for more articles on software engineering leadership and troubleshooting software engineering teams' problems.
