Documentation

General Documentation Guidelines

Documentation should be clear, concise, and consistent.

Clear

• 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

Concise

• Stay focused and on topic
• Organize your information logically and don’t repeat yourself
• Provide factual information rather than opinionated editorials

Consistent

• 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 Environment

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

Project Architecture

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.