Effective Documentation: When, How and Why

Introduction

In any project lifecycle, documentation is a critical tool to ensure knowledge is preserved and easily transferable, especially during team changes. Whether a developer leaves mid-project or a new team member joins in the middle of an ongoing task, having the right documentation in place is essential to avoid disruptions. In this blog, we’ll explore when and how to document, who should document, and how effective documentation practices can facilitate smoother transitions. We’ll also discuss common challenges and provide examples of essential documents and templates to streamline the process.

When to Document?

1. Before Development: Documentation should begin during the planning phase. The focus at this stage is on defining project requirements, architecture, and onboarding materials.
   • Project Requirement Specification (PRS): Captures all project requirements, objectives, use cases, and constraints.
   • Example Template:
   • PRS Template: This template includes sections for project overview, functional requirements, use cases, and acceptance criteria.
   • System Architecture and Design Decisions: Records initial architectural diagrams, technology stack decisions, and module descriptions.
   • Example Template:
   • Lucid chart Architecture Design Template: A comprehensive template for documenting system architecture and design decisions.
   • Onboarding Materials and Standards: Includes documentation for setting up the development environment, coding standards, and project onboarding instructions.
   • Example Template:
   • Notion Onboarding Template: This template guides new developers on project setup, coding standards, and workflow processes.
2. During Development: Documentation should be updated continuously as new features are added and code evolves. Key documents include:
   • Feature Specification Document (FSD): Describes each feature or module in detail, including its purpose, inputs/outputs, and dependencies.
   • Example Template:
   • Google Docs FSD Template: This template includes sections for feature overview, inputs/outputs, API references, and dependencies.
   • Code Documentation: Comments within the code and detailed explanations for complex logic or algorithms. Documentation tools like JSDoc (for JavaScript) or Doxygen (for C/C++) can be used.
   • Example Tool:
   • JSDoc: is a documentation tool for JavaScript codebase. It uses the comments in the code to generate the document.
   • Version History and Change Logs: All changes made in a codebase, for example, new features, bug fixes, and updates.
   • Example Template:
   • Change-log Template: https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md
3. During the Change Process: When moving a project to a new team or developer, having thorough documentation helps the new member quickly grasp the project's current status and requirements.
   • Transition Document: Captures the current state of the project, pending tasks, and specific knowledge the new developer might need to get started.
   • Example Template:
   • Google Docs Transition Document Template: Includes sections for project status, pending tasks, known issues, and any special notes for the new team.
   • Handover Checklist: A list of all project assets, credentials, and documentation links to ensure everything is handed over effectively.
   • Example Template:
   • Google Sheets Handover Checklist Template: A detailed checklist covering project assets, pending tasks, documentation links, and configuration notes.
4. Post-Completion (After Development): After the project is completed, it's important to document lessons learned and how to maintain the system for future use.
   • Post-Mortem Documentation: Document what works well, what does not, and lessons learned from a project lifecycle.
   • Maintenance Guide: This is a guide explaining how to maintain the system. It includes ways to troubleshoot the system, how to configure it, and contact information.

How to Document?

• Use a Consistent Structure: All documents have to be written in a standard format, either in a predetermined template, so consistency is maintained across all projects. This way, everyone can easily gain access and work their way through the documentation.
• Utilise Collaborative Tools: Tools like Confluence, Notion, or Google Docs allow team members to work on and share a document in real time with the chances of commenting and giving each other responses on each other's changes.
• Focus on Clarity and Brevity: Be simple and concise. Document in a tight style-with as little technical jargon unless meaningful to the technology or project, and defined in a glossary-requires.
• Use Visual Aids: Incorporate diagrams, flowcharts, and screenshots to explain complex processes or designs.

Who Should Document?

• Project Managers: Responsible for high-level documentation like project scope, requirements, and change management.
• Example Document: PRS, Transition Document.
• Developers: Handle code comments, technical documentation, and API specifications.
• Example Document: Feature Specification Document (FSD), Code Documentation.
• QA Engineers: Create test plans, test cases, and bug reports, ensuring traceability between requirements and test outcomes.
• Example Document: Test Case Documentation, Test Results Report.
• Product Owners or Stakeholders: Contribute to requirement documents, use case descriptions, and user stories.
• Example Document: Project Requirement Specification (PRS), Use Case Scenarios.

Collaboration is Key: Assigning roles ensures that no one person is overwhelmed and that documentation covers all aspects of the project.

Challenges in Documentation

1. Time Constraints: Developers and team members may see documentation as secondary to coding or testing, especially under tight deadlines.
2. Solution: Make documentation a mandatory thing of the Definition of Done (DoD) for each tasks.
3. Knowledge Gaps: If the person preparing the documentation doesn’t fully understand the topic, it may lead to incomplete or inaccurate information.
4. Solution: Encourage collaboration and peer reviews for critical documents to ensure accuracy.
5. Keeping Documentation Up-to-Date: As the project evolves, documentation can become outdated if not regularly updated.
6. Solution: Set up regular checkpoints (e.g., end of sprint reviews) to review and update documentation.

Future

The horizon of the documentation of projects is moving towards a time where the documentation of projects will be done through AI’s completely, allowing stakeholders to allocate their time, effort, and resources towards more important things such as development, strategy, and decision-making. There will be no longer needs for projects to take up days writing long descriptive reports or documenting how certain parts of the project have evolved since there will be AI-powered tools that will generate, update, and maintain documentation in real-time. With this however, Artificial Intelligence will take over this duty by recognising and recording important details during the course of the project as well as its abstract from unnecessary bulky information and up-to-date documentation all done without human intervention. This new environment will facilitate stakeholders to devote their attention to the creation and implementation of new concepts, leaving to AI the hassle of writing all the new material in a crisper and neater manner than it has ever been done before.

Conclusion

All projects require clear artefacts to be drafted, edited, and maintained. This is especially valuable where handovers and changes in management are common. Related to that: a clear ownership and a well-defined structure of the documentation, coordination of the changes in the team is a project-booster. It is however possible to streamline the processes through the use of the templates offered, the management of the knowledge and the projects will avoid such unnecessary downtime.