Writing good documentation
Links and useful resources
Concept summary and lesson
- We have a cool tanks game, and we're going to take a break from it for a while, so we need to make sure we have really good documentation that will let us pick it up again.
- Important things to document: What it does, what it expects, usage examples, where else in the code it is used.
- Where does this thing fit in the larger app?
Good documentation is focused on getting people to be able to dive in and use your code as quickly as possible. You want to help someone understand the whole app well enough to be able to look for the right things in the right places. It needs to be focused on the context that the user is probably working in to make sure you're answering the right questions:
- What is the overall, big-picture structure of this app?
- Logical blocks of functionality
- Flow of data
- Why is this code here?
- Where does it fit within the larger app?
- What other ways are there to do something like this?
- Are there any exceptions or restrictions?
- Can this code cause crashes, panics, or throw exceptions?