Anatomy of a Design Document #53
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Strengthen "The Principles of Clarity" section by making the principles more impactful with more context and examples.
* **Add the "Why":** For each principle, you could briefly explain *why* it's important. For example, for "Use Short, Direct Sentences," you could add that it reduces cognitive load on the reader.
* **Incorporate a "Before and After" Example:** Showing a principle in action is very powerful. For instance, under "Replace Adjectives with Data":
```/dev/null/example.md#L1-4
* **Before:** The new service will be very fast and significantly more scalable.
* **After:** The new service will have a P99 latency of <200ms for up to 10,000 requests per second.
```
You already have a similar example, but framing it as a direct before/after could make it more explicit.
* **Add a Principle about the Audience:** A key theme in the reference articles is being audience-aware. You could add a principle like: "**Write for Your Audience**." This would involve advising the writer to consider who will be reading the document (e.g., their own team, a different team, leadership) and to adjust the level of technical detail accordingly.
"Anatomy" Section is the core of your article and is already very detailed. Here are a few minor suggestions to make it even more robust.
* **Expand "Title and People":** You could suggest thinking about roles more explicitly, inspired by RACI (Responsible, Accountable, Consulted, Informed). You don't need to explain the whole framework, but you could refine the list:
* **Author(s) (Responsible):** The primary writer(s) of the document.
* **Accountable:** The person ultimately answerable for the project's success (e.g., Tech Lead, Engineering Manager).
* **Reviewer(s) (Consulted):** Key stakeholders who provide feedback.
* **Add a "Steel-Manning" Note:** In the "Alternative Solutions Considered" section, you can add a sentence encouraging the author to "steel-man" the alternatives—that is, to represent them in their strongest possible form. This demonstrates intellectual honesty and ensures the chosen solution is truly the best one, not just the one you initially favored.
* **Include "Data Privacy":** Your "Cross-Cutting Concerns" list is excellent. I suggest adding one more item: `Data Privacy`. It is related to security, but with regulations like GDPR and CCPA, it's often a distinct and critical concern. It would address questions like "Does this design handle user data? If so, what personally identifiable information (PII) is stored, and how are we protecting it and managing user consent?"
Add a Section on the "Document Lifecycle" A design document isn't just written and forgotten. It goes through a process. Adding a short section on this can help set expectations for engineers new to writing them. You could add a section titled "**The Lifecycle of a Design Document**" that covers: 1. **Drafting & Iteration:** Emphasize that the first version is never the final one. 2. **The Review Process:** Describe the importance of getting feedback, starting with a small circle of trusted peers and then expanding to a wider group of stakeholders. 3. **Approval:** What "approval" means—it's not a contract set in stone, but an agreement to proceed. 4. **A Living Document:** Mention that the document might be updated during implementation as new information comes to light. Afterward, it serves as a valuable historical record.
Enhance the Conclusion The current ending is a friendly sign-off. Add a concluding paragraph to summarize the key takeaways and leave the reader with a final, powerful thought. For example: ```/dev/null/conclusion.md#L1-4 A great design document is more than a project blueprint; it's a tool for thinking. The process of writing it forces you to clarify your ideas, anticipate challenges, and align your team. By focusing on clarity and embracing a structured approach, you can create documents that not only guide implementation but also build a shared understanding and lead to better engineering outcomes. ```
dzlab
force-pushed
the
article/design-doc
branch
from
4e4c7a7 to
c3a9037
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.