Clarity is paramount. Use precise and unambiguous language.
Provide a glossary for technical terms
Provide acronyms and their meaning
Each sentence should convey a single, clear idea.
Conciseness is important. Be brief and to the point.
Remove unnecessary words, phrases and redundancy (“filler”).
Shorter sentences improve readability and scannability of text.
Accuracy of the information is important. The Architect needs to be aware of the deep technical details of what he is overseeing.
Track Audience Awareness and change your approach of needed. Tailor the content accordingly based on technical background and understanding
Structure & Organize the documentation in clear headings, subheadings and paragraphs.
Completeness of the information helps remove misunderstandings. The documents provided by architects should give enough information and provide enough context.
Be Consistent in grammar, tone, style and formatting.