Creating and maintaining effective documentation is expensive, and often under-prioritized when a team has a deep backlog of work. However, well written documentation is an invaluable mechanism for knowledge sharing and communication. Well-executed documentation effectively shares important knowledge across a team, improves productivity and breaks down information silos. Below are 5 lightweight, effective forms of documentation that help capture important knowledge across a team's software development process.
1. README.md
Including a README.md file directly with the source code is an easy way to document basic information about how to work with software. Typical content for a good README.md includes basic information about the purpose of the system, how to build and run the software, and links to relevant CI/CD pipelines and related software.
2. CONTRIBUTING.md
A CONTRIBUTING.md file can also be included with the source code to describe how to contribute to the code. CONTRIBUTING.md can include brief descriptions of things like overall code organization, how to test and submit bug fixes, expectations for code comments, and more.
3. Checklists and Standard Operating Procedures
Checklists and Standard Operating Procedures(SOPs) are an underrated mechanism for reducing human error and codifying important processes. Create a repository of checklists and SOPs for things like testing processes, code review steps, any manual deployment steps, and other routine tasks.
4. HOWTO / FAQ
Keeping a document that details common tasks and Frequently Asked Questions (FAQs) is a great way to document team knowledge that may not fall in to a typical README or CONTRIBUTING document. These can be things like "how do I find logs for X", "How do I add a new service to the system?", "How Do I debug a failed deployment?" and other questions can be documented in a FAQ or HOWTO document.
5. Architecture Decision Records
Architecture Decision Records (ARDs) are a great way to document not only "what" but "why" important decisions were made on how to implement important parts of a system. Documenting the evaluations and rationale of important design decisions in a lightweight format is an invaluable tool for passing down knowledge across a team.
While there are many ways to document and track knowledge across a team, these are a few ideas for creating lightweight documentation that I've personally used with success across teams. What other ways have your teams successfully captured key knowledge of software and systems?
Top comments (0)