General Documentation Guidelines
Documentation should be clear, concise, and consistent.
- Define all abbreviations. i.e. define Three Letter Acronyms (TLAs) the first time then you can abbreviate TLAs subsequently.
- Define all terms
- Don’t assume the reader knows what you’re talking about. Declare pre-requisite knowledge up front.
- Give examples
- Stay focused and on topic
- Organize your information logically and don’t repeat yourself
- Provide factual information rather than opinionated editorials
- Look at other documentation and follow similar patterns
- In general we should attempt to provide:
- Overview (what you’re going to tell them)
- Body (tell them)
- Examples (show what you told them)
- Follow up (where can they hear more about what you told them)
- Keep things up-to-date
Development environments should always be documented in a Readme at the root level of the project repo. Include at a minimum:
- a brief on what the project is
- the technology stack
- any pre-requisites
- Quickstart guide for getting setup and running
- the file structure of the project
- links or note of where to access server environments, access credentials, and any external dependencies
Architecture documents location and composition will be determined at the team and project level
Technical Design Documents
TDD location and composition will be determined at a team and project level
High Level Processes
All high level technical documentation is included in our internal wiki. Consult with other developers or technical directors for guidance if needed. Try to be complete, concise, and clear.