arch-doc
The Documentation Must Be Clearand Concrete• What matters is that the architecture is explained asclear and precise as possible.• There are many templates for architecture documents,remember that they must be adapted! They are agreat source for ideas, but do often containunnecessary sections that must be removed. Theymight also lack sections that are actually needed.Architectural Documentation 4
How To Explain?• A good approach is to start by writing body text, and then clarify the textwith code snippets, UML diagrams, user interface screenshots and otherimages.• Text and images complement each other, both are needed. Images shall benumbered, have captions and be explained in the body text.• Assume that the reader has the same knowledge as those who wrote theprototype, except that she/he does not know anything about thisparticular application.• Ask yourself what you would like to know if you were to take overmaintenance of this application.• Pay extra attention to thoroughly explain things you found hard to solve.Architectural Documentation 5
- Page 1 and 2: Architectural DocumentationArchitec
- Page 3: The Prototype is Also Part of theDo
- Page 7 and 8: Functionality View• The functiona
- Page 9 and 10: Design View (cont’d)• It is oft
- Page 11 and 12: Data View• The data section shall
- Page 13 and 14: Implementation View• The implemen
- Page 15 and 16: Problems View• The problems secti
- Page 17 and 18: Common Mistakes• No or irrelevant
- Page 19: Common Mistakes (cont’d)• No in
How To Explain?
• A good approach is to start by writing body text, and then clarify the text
with code snippets, UML diagrams, user interface screenshots and other
images.
• Text and images complement each other, both are needed. Images shall be
numbered, have captions and be explained in the body text.
• Assume that the reader has the same knowledge as those who wrote the
prototype, except that she/he does not know anything about this
particular application.
• Ask yourself what you would like to know if you were to take over
maintenance of this application.
• Pay extra attention to thoroughly explain things you found hard to solve.
Architectural Documentation 5
Change language