Ask HN: Are there any openly available software architecture documents? I'm about to leave my job for another and i'm tasked with documenting the existing architecture and flow of the app. I'd also have to document why certain decisions were taken. I'm looking for any openly available similar documents for guidance mostly around how to structure the document. |
It is an opportunity to learn and apply it forward to your new job.
import: Diagram
ok: Community
see: https://www.drupal.org/project/project_module?f%5B2%5D=im_vi...
But for general structure, using your end-user's user experience path (from start to end) as a guide and avoiding buzzwords as much as you can usually help. Think of Stripe's documentation, you want something as easily digestible as that.
- Software Design Patterns: https://en.wikipedia.org/wiki/Software_design_pattern
- Azure Application Architecture Guide: https://docs.microsoft.com/en-us/azure/architecture/guide/
- Azure Cloud Design Patterns: https://docs.microsoft.com/en-us/azure/architecture/patterns...
- Azure Architecture Framework: https://docs.microsoft.com/en-us/azure/architecture/framewor...
- Azure Cloud Adoption Framework: https://docs.microsoft.com/en-us/azure/cloud-adoption-framew...
- Cloud Computing Patterns: https://www.cloudcomputingpatterns.org/
- Microservice Architecture Patterns: https://microservices.io/patterns/index.html
- Amazon's Builders Library: https://aws.amazon.com/builders-library/
Also, for a 10,000 foot overview of popular open-source tools, see https://aosabook.org
As someone who only really gets exposure to web tech, it was fascinating how other types of software is architected, too.
Perhaps Effective C++ comes in second, but that's just b/c C++ is a nightmare.
https://arc42.org/documentation/
PRINCE 2 documents also come with a 'decision log', if you want something in a formal template.
[2] and [3] list a few example documents for Software Architectures, you can google further and find some more.
I think reading through a few sample documents and based on the expectations at your current job, you can derive the necessary doc.
[1] https://www.amazon.com/Documenting-Software-Architectures-Be...
[2] https://projects.cecs.pdx.edu/attachments/download/3146/Soft...
https://aws.amazon.com/whitepapers/?whitepapers-main.sort-by...
I’m also a big fan of DDD [2] and use his “box and line” drawings all the time. There are loads of resources for DDD but I’ve linked to the book, which is awesome. DDD has great concepts like Context Boundaries and Ubiquitous Language which may simplify the documentation process.
It’s easy to think of architecture too abstractly or in terms of frameworks or other complexifying concepts, but simple is good, and that’s true from top to bottom.
[1] http://www.developerdotstar.com/mag/articles/reeves_design_m...
[2] https://www.goodreads.com/book/show/179133.Domain_Driven_Des...
https://www.cs.colorado.edu/~kena/classes/5448/f12/presentat...
Yes please. So much this. With evidence, please, so that the decisions can be revisited in the future and changed when they no longer apply. Every day I open another source file on a system that was built over a decade by a rotating cast of mostly first job software engineers without adequate mentorship and (I wish I was making this up) having their C++ code reviewed by a C programmer who gave them comments such as "just turn all these functions into one-line macros", and someone who appeared to be mainlining late-nineties OOP hype like it was going out of fashion and needed to get it all on the page before someone beat him to death with an old Vic 20.
Every day we stare at it and ask ourselves why. Why was it done like this? Was there a good reason back then? Does that reason still exist? If I rewrite it to remove all this horror, will something else break? Even, oh God, even "What is this actually meant to do?" I can see what it does do. What it does do makes no sense. Did it ever make sense?
Even the occasional comment like "cheeky hack for performance" is often more hindrance than help when a quick test shows it actually makes performance worse. Did it ever improve things? Did the hardware change underneath it such that it no longer helps? Did other code change such that it no longer applies?
Anyway, where this was going is that a decision recorded without evidence or even the factors considered might as well have been a coin toss to the software archaeologist having to maintain it in a decade's time. If the decisions and reasoning aren't recorded, you're forcing someone to attempt to reverse-engineer your state of mind, and that's an expensive and impossible job.
For decisions a table with some explainatory comments why you have decided to use this one thing and which alternatives you have considered and why those did not make it, helps. You can look up ADRs. (Decision Records)
It contains architecture overviews of many open source projects.
Meta information could be: Status, stakeholders, decision-makers, and rollout description. It also often has links to meeting protocols and tickets.
https://github.com/VCTLabs/MIL-STD-498/raw/master/MIL-STD-49...
The US Military came up with their own standard for systems and software development (MIL-STD-498), which as evolved into IEEE and ISO standards. The nice thing about the US Military's standards is that they came with Data Item Descriptions (DIDs) that specify exactly what goes in each document.
Also, while this bit is probably overkill for your current situation, you may find value down the road in looking at some of the various "architecture frameworks"[4] and reference models that are out there. Things like TOGAF[5], DODAF[6], MODAF[7], TRAK[8], etc.
In any case, always remember the words of the immortal Bruce Lee:
“Absorb what is useful, discard what is useless and add what is specifically your own”.
[1]: https://en.wikipedia.org/wiki/Philippe_Kruchten
[2]: https://en.wikipedia.org/wiki/4%2B1_architectural_view_model
[3]: https://www.amazon.com/Software-Systems-Architecture-Stakeho...
[4]: https://en.wikipedia.org/wiki/Enterprise_architecture_framew...
[5]: https://en.wikipedia.org/wiki/The_Open_Group_Architecture_Fr...
[6]: https://en.wikipedia.org/wiki/Department_of_Defense_Architec...
https://github.com/joelparkerhenderson/architecture_decision...
There are multiple variants. Simple or detailed.
You don't put every little decision in of course, but most projects have at least 1-2 areas where even the people involved with the decision have a hard time recollecting all the context for the decision.
The downside, at least for OP, is that they're usually something you capture at the time the decision is made - not when you're leaving a project.
[1] https://github.com/milo-minderbinder/AWS-PlantUML [2] https://real-world-plantuml.com/
Architecture: this is often documented with some kind of diagram. I personally find them to be unhelpful.
Flow: I'm guessing people aren't familiar with your UI. The best way to document would be to record a video, but that might be a little extra. I would make a powerpoint doc with screenshots to show the common flows.
For me, it kinda looks like this:
- Assume expertise in the individual technologies you've used
- If you picked the tech, then write why you did, and link to resources to learn more about it
- Write down which general constraints I placed on myself that might not be common. EX: naming patterns, cyclomatic complexity, using a functional approach, or being more point-free in a language where it's not common, choices around duplicate code
- Make a nested list of the folder structure and describe what each folder is for (even if it feels obvious), and describe how the different parts interact with each other. The questions to answer are: what are the high-level dependencies between dirs? Are there any cyclical dependencies?
- Find the knots (especially complex parts of the codebase) and make sure they're documented properly
For documenting decisions on architecture this should be done as you go really but better late than never :). Using adr ( architecture decision records ) text / md files would be my approach. They will typically be kept alongside the code and source controlled
Stuff that can be formalized in a systematic manner is usually stuff you can figure out on your own in a text editor or IDE.
I feel like resorting to simple hand drawn diagrams, is in a way declaring failure on being able to describe complex software requirements and structure/ behavior in a systematic graphical manner.
Then work on refining, editing, deleting, modifying.
Separate the creation from the editing/communication.
I'm doing this now for a couple of things I've inherited because my predecessors either never documented it or it's been lost to time. High-level flow, tricky and/or problematic bits with operational & recovery info, then the mundane as I have time. That means the mundane or some of the less-tricky tricky bits will be "vague" for a while.