See also Software Development Methodologies
documentation
- Comments
- Readme
- Wiki
specification
- UX
- UI
- High-Level Architecture (libraries, external APIs)
- Low-Level Architecture (modules, functions, internal APIs)
commenting
- Almost anything hardcoded (constants, strings, etc.)
- Anything confusing, tricky, nonstandard
- Historical notes: if something is added/removed, write it down
- TODO for bugs or hacks
README Files
- Best used as a quick-start guide
- What are key pieces of info they will pieces of info they will need?
- What is your code supposed to do?
- How does someone run your code?
- How does a new engineer get set up?
- General overview of how things are laid out, with links to wiki pages with details
Wiki
- In-depth explanation of subsystems and modules
- Separate pages for each subsystem
- Include decisions of their design decisions
- Discussions of why systems are not designed differently
UI/UX Spec
- How do we know what the software is supposed to do?
- Varying levels of resolution
- User stories
- All the way up to granular details of UI elements
Don’t forgot to document defaults!