Leveraging an AI-powered development workflow, such as utilising large language models (LLMs), makes it easier to create and maintain high-quality, readable documentation. This section outlines best practices for incorporating documentation into your development workflow and how to maximise the benefits of LLM capabilities.
During the normal development workflow, it is essential to update documentation regularly. Each time you introduce a new feature, refactor existing code, or resolve a bug, ensure that the corresponding documentation is revised to reflect these changes. This practice not only benefits human collaborators but also ensures the LLM has an accurate understanding of the current state of the codebase.
Use the prompt-update-documentation prompt to have the LLMs update the codebase documentation regularly.
Consider documentation as an integral part of the development lifecycle (ref: workflow-development-and-testing), not a separate task to be completed later. LLMs make it straightforward to maintain clear and consistent documentation as you work, generating drafts for function descriptions, usage guides, and even API documentation in real-time.
LLMs can generate complex visual aids to support documentation, improving clarity and understanding. Examples include:
- Sequence Flow Diagrams: Use tools like Mermaid or similar to depict workflows, interactions, and dependencies clearly.
- Conceptual Data Models: Visualise database schemas, entity-relationship diagrams, and other structural elements to provide a comprehensive understanding of the system.
These visuals help developers, stakeholders, and the LLM itself to contextualise the system's design and logic effectively.
Good documentation is not merely a static reference; it creates a feedback loop for the LLM. By providing detailed, up-to-date information about the codebase, the documentation becomes a critical resource for:
- Assisting the LLM in understanding the context for future development tasks.
- Reducing the likelihood of errors or redundant changes in the code.
- Enhancing the LLM's ability to predictively generate solutions aligned with existing patterns and architecture.
As the codebase grows, the importance of comprehensive documentation increases. Without it, the LLM’s effectiveness in managing and evolving the system diminishes. Regularly revisiting and enriching documentation ensures that both human and AI contributors can operate efficiently in a complex development environment.
- Treat documentation updates as part of your definition of "done" for each development task.
- Use LLMs to draft, review, and refine documentation continuously.
- Integrate tools like Mermaid for visualisation to enhance clarity.
- Regularly review documentation to ensure accuracy, completeness, and relevance.
By embedding these practices into your development workflow, you can ensure a robust, scalable, and efficient system that benefits from both human and AI collaboration.