From f290fa18bc6b37632849b5c1f606ed3f62a4cf35 Mon Sep 17 00:00:00 2001 From: Jordan Robinson Date: Sun, 19 Oct 2025 15:51:45 +0100 Subject: [PATCH] add tips / help section --- README.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b9dcad901a07595bce10beb3fa7edfd73ef24d62..eab3ac1a157b732cef803a12852675e3f9788496 100644 --- a/README.md +++ b/README.md @@ -14,4 +14,34 @@ Comprehensive collection of templates for solutions design, architecture decisio * Technical Debt Registry * Capacity Planning & Scaling Document * Incident Postmortem -* Technology Radar / Tech Stack Review \ No newline at end of file +* Technology Radar / Tech Stack Review + +## Tips to Keep In Mind... + +### ... When Writing + +**Be concise but comprehensive:** Include enough detail for someone unfamiliar with the request to understand the solution without unnecessary verbosity. + +**Use visuals:** Include architecture diagrams, sequence diagrams, or data flow diagrams where they clarify the design. + +**Focus on decisions:** Explain the "why" behind technical choices, not just the "what." + +**Tailor as needed:** Adapt these templates to your organization's standards and processes. + +**Link Related Docs:** Cross-reference related ADRs, runbooks, and design documents. + +**Involve Teams:** Make documentation a collaborative process; get input from the team who lives with these systems daily. + +### ... For Maintaining + +**Plan for change:** Use version control for your documentation and track significant revisions. + +**Keep it maintainable:** Use consistent formatting and structure across all design documents. + +**Maintain Consistency:** Use these templates consistently across your organization for familiarity and ease of use. + +**Make Searchable:** Store documentation where it's discoverable—wiki, internal docs site, knowledge base. + +**Keep Current:** Set review dates and assign owners to keep documentation fresh. + +**Review Cadence:** Architecture and operational guides should be reviewed quarterly; incident postmortems immediately after incidents; technology radar quarterly. \ No newline at end of file