Pranav Kasetti

The core method behind my variation of DDD is as follows. If you take anything away from this article, it's the following:

Feature release cycle

1. Write/update high-level feature documentation based on bug ticket, context from technical conversations, and project information.
2. Develop feature according to spec.
3. Update documentation with relevant low-level technical information, if needed, during development.
4. Generate documentation from the commented public interface (source code) of project using a Documentation Compiler. e.g. DocC in iOS/Apple ecosystem, pandoc in Python etc.
5. Store documentation in Version Control for revision tracking.

This is a very powerful workflow, and helps not only developers, but even project managers to understand the project. It supports my principle of being open, because bad decisions are much harder to make if everybody can see/review them and easier to fix.

DDD only works effectively if it's implemented project-wide. My current guidelines to do this comprehensively are documented below. I personally think great documentation is worth the extra investment so I plan to advocate for it in my future work.

Guidelines for project-wide DDD:

1. Capture high-level details into documentation immediately on team consensus. e.g. post-meeting, sprint review.
2. Organise documentation into clear site paths. Ensure understandable URL paths.
3. Complete lower-level documentation and link to high-level docs.
4. Consider what would be helpful for new-joiners to know, don't ramble and focus on what matters.
5. Add last modified date, and author to each page.
6. Manage access control: Restrict external access to internal documentation, and limit internal access to relevant teams.
7. Check documentation into Version Control for every change.
8. Implement DDD Feature Release Cycle for each Jira ticket.
9. Spell-Check / Lint documentation for every commit via CI tooling.

High-Level Documentation

1. Project Overview
2. Project Guidelines
3. Architecture Overview
4. Testing Practices
5. API Overview inc. Design Decisions
6. Workflow Overview
7. Tooling Overview
8. Security Overview
9. Project Style Guide
10. Subsystem Overview
11. Analytics Providers
12. Other Third-Party Dependencies
13. Features Overview
14. T&Cs and Privacy Policy

Low-Level Documentation

1. Getting Started Documentation
2. API Versions, OS Versions, Devices supported
3. Code Review Guidelines
4. PR Template
5. API Implementation
6. How to Use Version Control
7. App Guidelines e.g. Slack Usage, Conferencing w/ Teams or Zoom etc., StackOverflow Teams, Emails, Postman, Dash, Figma, SQL DB Viewer
8. Jira Usage Guidelines
9. Testing Frameworks and Patterns
10. Analytics Login details
11. App Distribution Processes (internal + external) inc. logins
12. Major Migration Details from old DB, OS or tooling versions

API Implementation

1. Microservices Architecture
2. API Types e.g. OAuth
3. Public API Interfaces w/ function signatures, example request/response formats
4. Test API Tokens
5. Test Login Details
6. Test Payment Details

After project-wide initial documentation has been completed, stabilised and approved, we can now update the documentation for every feature, and incrementally ensure all documentation is at parity with the app.

Note

This methodology is subject to change, and I may update this in the future with further improvements based on my experience. Feel free to let me know if I am missing anything, or if you have feedback to improve further. I haven't actually implemented the below in a live project yet, but will update this post when I do (soon!). Thanks.