Tips on process of writing design document

As a senior team member or technical manager, creating design documents helps you in achieving organizational challenges such as scalability, maintainability, or reliability.

For example At Twiga, where I previously worked, we quickly realized the immense value of good architecture that could be intuitively understood, especially as new engineers joined the team. No amount of documentation can replace a system that intuitively lets the engineer know what is possible with it.

A well-crafted design document ensures that system goals are met and minimizes future redesigns and rewrites. Here's how to approach creating an effective design document:

1. Use diagrams liberally: Start with a block diagram featuring 4-6 main components and their interactions. This provides a quick overview of the system for anyone examining it.
2. Include a sequence diagram: Illustrate the flow of data and processes. This clarifies the order of operations within the system.
3. Add deeper content: Provide analogies, examples, and estimates for those delving deeper into the document.

I recommend that the first draft be created by a single senior engineer or technical manager. Once complete, iterate on it through the following process:

1. One-on-one sessions: Discuss the draft with other engineers individually. This helps identify issues before group meetings and allows for free expression of disagreements.
2. Team review: Present the revised document to the larger team for finalization.
3. Leadership sign-off: If necessary, seek approval from higher-ups as the final step. This prevents premature influence from leadership that might discourage team input.

By following this process, you'll create a comprehensive design document that serves as a valuable guide for your engineering team and ensures clarity in your system's architecture.