Tips for Efficient Writing

When writing TechDocs or ADRs, keep these tips in mind:

  • Be Concise: Keep sentences and paragraphs short and to the point.
  • Use Subheadings: Break down content into sections with clear subheadings for easier navigation.
  • Include Visuals: Use diagrams, screenshots, or code snippets to illustrate complex concepts.
  • Stay Focused: Stick to the topic and avoid unnecessary tangents.
  • Review and Edit: Proofread your doc for clarity, coherence, and grammatical accuracy.
  • Use Examples: Provide concrete examples to illustrate abstract concepts.
  • Consider Your Audience: Write with your intended readers in mind, adjusting the level of technical detail as necessary.
  • Update Regularly: Keep your documentation up-to-date as the architecture or decisions evolve.

By following these tips, you can write efficient, well-organized docs that effectively communicate your message.

References

  1. https://learn.microsoft.com/en-us/azure/architecture/browse
  2. https://aws.amazon.com/architecture/reference-architecture-diagrams
  3. https://cloud.google.com/blog/products/application-development/13-popular-application-architectures-for-google-cloud