How do you share software architecture?
Software architectures rarely live in isolation and at some point other people will need to know about them. These people could be members of the immediate project team or other stakeholders representing operations, support, database administration, security and so on. However you choose to share this information, it should be complementary to the code and describe what the code itself doesn't. But how do you do this? Read on and find out.
The code doesn't tell the whole story
We all know that writing good code is important and refactoring forces us to think about making methods smaller, more reusable and self-documenting. Some people say that comments are bad and that self-commenting code is what we should strive for. And I don't disagree. Everybody *should* strive for good code that's easy to read, understand and maintain. But the code doesn't tell the whole story. Read more...
Sharing architecturesDocumentation is just one option for sharing software architectures; there are many others waiting to be explored.
|
Documenting your software architecture
|
Software architecture document guidelinesRead our guidelines for writing software architecture documents.
|
Example architecture diagramsSee some example diagrams used to describe software architectures from different perspectives.
|
Presenting architecture
- Project Naming - what's in a name?
- Style on top of substance... - PowerPoint architecture is very different from sharing architecture by PowerPoint!
- PowerPoint architects - some resources for improving your presentation skills.
- Upselling your architecture - your audience should drive how you present your architecture.
Documenting architecture
- Is UML on the way out? - is UML a viable option for documenting architectures?
- What's your UML tool of choice? - how do you draw UML diagrams?
- The Enid Blyton effect - sharing information via a wiki can be good, but there are some pitfalls to watch out for.
- How much software design detail in your architecture document? - you've decided to document your architecture, but how much detail do you include?
- Service catalog - if you have open services, you should advertise them.
Read more
You can see more content discussing how to document and share software architecture in our How do you share software architecture? category.
