5 ms·

Ask HN: Are there any openly available software architecture documents?

• zeko1195 7y ago
  AWS has nice whitepapers on their software architecture. https://aws.amazon.com/whitepapers/?whitepapers-main.sort-by=item.additionalFields.sortDate&whitepapers-main.sort-order=desc https://aws.amazon.com/whitepapers/?whitepapers-main.sort-by...
• deepaksurti 7y ago
  The book `Documenting Software Architectures ...` [1] can help. [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-Beyond-Engineering-ebook/dp/B0046XS3RO https://www.amazon.com/Documenting-Software-Architectures-Be... [2] https://projects.cecs.pdx.edu/attachments/download/3146/Software_Architecture_Document.docx https://projects.cecs.pdx.edu/attachments/download/3146/Soft... [3] https://www.voa.va.gov/DocumentView.aspx?DocumentID=188 https://www.voa.va.gov/DocumentView.aspx?DocumentID=188
• blowski 7y ago
  C4 is pretty easy to learn, Arc42 has some sample documents that are very useful. They complement each other. https://c4model.com/ https://c4model.com/ https://arc42.org/documentation/ https://arc42.org/documentation/ PRINCE 2 documents also come with a 'decision log', if you want something in a formal template.
• myrloc 7y ago
  PlantUML is useful for diagramming anything from sequences to system architecture to state machines. It's also widely supported in many modern text editors like emacs and VSCode. PlantUML components for AWS are widely available [1]. You may find RealWorldPlantUML a good place to start looking for examples [2]. [1] https://github.com/milo-minderbinder/AWS-PlantUML https://github.com/milo-minderbinder/AWS-PlantUML [2] https://real-world-plantuml.com/ https://real-world-plantuml.com/
• exabrial 7y ago
  Yikes, if you haven't been doing this as you go you've severely messed it up.
  • deleted 7y ago
    [deleted]
• Ididntdothis 7y ago
  Don’t do it like me and overthink it. Just write down all your thoughts informally. Make diagrams by hand. Only once you have most content then think about formatting and structure. A lot of people produce nicely looking docs without much content. I much prefer a bunch of simple notes that describe the thought process
  • JamesBarney 7y ago
    So much this. Working for Enterprise I saw so many 20 page architectural documents that were borderline impossible to parse and were about as illuminating as a 30 second conversation.
  • billfruit 7y ago
    But then it is all .. vague. I do hope something better than can be done.. hand drawn diagrams can't represent details at different levels of magnitude, like for example why statecharts are very expressive compared to other diagrams is it's ability to have arbitrary levels of nesting, which is not possible with handdrawn or even printed diagrams. 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.
    • Ididntdothis 7y ago
      Just make sure your stuff really expresses something and isn’t just pretty as I see quite a bit.
    • davengh 7y ago
      The details will always have to be looked at by the inheritors - it's more important to not say something wrong or contradictory IMO. When I've had to do something like this in the past I circle through it, documenting the high-level ops before details anywhere. Tricky or especially complicated details next, then the operational details for as much as I've time for. 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.
• TruffleLabs 7y ago
  If you only have a few weeks then there might not be any good results: you have to spend time learning the framework and also provide the relevant/ required info. It is an opportunity to learn and apply it forward to your new job.
• deleted 7y ago
  [deleted]
• Naac 7y ago
  I would also look at "The Architecture Of Open Source Applications", although it might be more detail than you're looking for.
• bhamp0 7y ago
  Archi software to draw Archimate diagrams.
• jupp0r 7y ago
  There is the excellent Architecture of Open Source Applications book, which is available online for free at http://aosabook.org/en/index.html http://aosabook.org/en/index.html It contains architecture overviews of many open source projects.
• nullandvoid 7y ago
  I agonized over the best way to do this stuff for a while also and the best framework I've used so far is the C4 model (as mentioned elsewhere). 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
• kejaed 7y ago
  This might initially look to be be a little too specific for military / aerospace, but it can act as a good guideline for a table of contents and examples of what might go in each section. https://github.com/VCTLabs/MIL-STD-498/raw/master/MIL-STD-498-templates-pdf/SDD-DID.pdf 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.
• weitzj 7y ago
  Plantuml for drawing pictures together with the C4 Plantuml Plugin is helpful. i.e. you make high level overviews of your architecture and then „zoom in“ 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)
• qznc 7y ago
  Our design decision documents have essentially four sections: Problem description, solution options, comparison of the options, and decision. I find it helpful to clearly distinguish what is part of the problem and what part of the solution. The size of the sections varies a lot. Meta information could be: Status, stakeholders, decision-makers, and rollout description. It also often has links to meeting protocols and tickets.
  • crocal 7y ago
    These are not architecture documents but change management documents. Roll out of such decisions should, among other things, result in an update to architecture docs.
• claudiulodro 7y ago
  There are dozens at the Architecture of Open Source Applications ebook/site: http://aosabook.org/en/index.html http://aosabook.org/en/index.html As someone who only really gets exposure to web tech, it was fascinating how other types of software is architected, too.
  • mthoms 7y ago
    Wow, what a great resource. Thanks for sharing.
  • godelmachine 7y ago
    Highly recommend AOSA
  • cheez 7y ago
    The best book/pair of books about software that I have ever read. Perhaps Effective C++ comes in second, but that's just b/c C++ is a nightmare.
    • ahartmetz 7y ago
      Effective C++ is mostly just a book about C++ pitfalls to avoid. It says nothing about high level concepts.
      • deleted 7y ago
        [deleted]
• bvogelzang 7y ago
  I've found this to be a pretty great resource: https://github.com/joelparkerhenderson/architecture_decision_record https://github.com/joelparkerhenderson/architecture_decision...
• NicoJuicy 7y ago
  ADR is made for this https://github.com/joelparkerhenderson/architecture_decision_record https://github.com/joelparkerhenderson/architecture_decision... There are multiple variants. Simple or detailed.
  • lllr_finger 7y ago
    ADRs are great, and don't need to be overly formal or use tooling. We've been hand-writing Markdown-based ADRs (https://github.com/adr/madr https://github.com/adr/madr) checked in with our code in a docs/adr directory. 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.
• lanstin 7y ago
  Most important thing to convey is the conceptual framework used and assumptions made to simplify things. e.g. "We will fix problems only by altering the base image, not the build system." "We will not change to 64-bit build as a part of this change." The sort of thing so that if someone really internalizes the perspective, they will be able to decide all the details on their own. Also a basic picture is always very popular. The details should be in git someway or another, but being able to use the details quickly is the job of the overview. I find it useful to document common change workflows ('To add another type of processor, add the class name to this map in this file, provide a jar implementing that class here, and add a new ID to the enum here.')
• mister_hn 7y ago
  GitLab has all of their docs online..I guess you can dig into them for inspiration
  • Carl_Platt 7y ago
    Do you have a specific link one can start digging through?
• davalapar 7y ago
  There are bunch of them, really. 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 https://en.wikipedia.org/wiki/Software_design_pattern - Azure Application Architecture Guide: https://docs.microsoft.com/en-us/azure/architecture/guide/ https://docs.microsoft.com/en-us/azure/architecture/guide/ - Azure Cloud Design Patterns: https://docs.microsoft.com/en-us/azure/architecture/patterns/ https://docs.microsoft.com/en-us/azure/architecture/patterns... - Azure Architecture Framework: https://docs.microsoft.com/en-us/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-framework/ https://docs.microsoft.com/en-us/azure/cloud-adoption-framew... - Cloud Computing Patterns: https://www.cloudcomputingpatterns.org/ https://www.cloudcomputingpatterns.org/ - Microservice Architecture Patterns: https://microservices.io/patterns/index.html https://microservices.io/patterns/index.html - Amazon's Builders Library: https://aws.amazon.com/builders-library/ https://aws.amazon.com/builders-library/
  • ignoramous 7y ago
    Apache Kafka's documentation is pretty good, too: https://kafka.apache.org/0102/documentation.html https://kafka.apache.org/0102/documentation.html Also, for a 10,000 foot overview of popular open-source tools, see https://aosabook.org https://aosabook.org
• cgarvis 7y ago
  I found the 4+1 architecture docs very helpful when working with a recent client. https://en.m.wikipedia.org/wiki/4%2B1_architectural_view_model https://en.m.wikipedia.org/wiki/4%2B1_architectural_view_mod.... What I like about it is that it separates the architecture into four views each for a different audience
• mitchtbaum 7y ago
  import: English import: Diagram ok: Community see: https://www.drupal.org/project/project_module?f%5B2%5D=im_vid_3%3A116 https://www.drupal.org/project/project_module?f%5B2%5D=im_vi...
• harshulpandav 7y ago
  Making use of colors in architectural diagrams really add depth to the information. Often applications involve internal and external (out of scope) components. Using common colors for each group of components really helps in the readability.
• luxuryballs 7y ago
  Tell them the code is so good it documents itself.
• mindcrime 7y ago
  I am a fan of Phillipe Krutchen's[1] "4+1" model[2], or variants thereof. The book Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives[3] by Eoin Woods and Nick Rozanski is a really good overview of the overall mechanism. 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 https://en.wikipedia.org/wiki/Philippe_Kruchten [2]: https://en.wikipedia.org/wiki/4%2B1_architectural_view_model https://en.wikipedia.org/wiki/4%2B1_architectural_view_model [3]: https://www.amazon.com/Software-Systems-Architecture-Stakeholders-Perspectives/dp/0321112296 https://www.amazon.com/Software-Systems-Architecture-Stakeho... [4]: https://en.wikipedia.org/wiki/Enterprise_architecture_framework https://en.wikipedia.org/wiki/Enterprise_architecture_framew... [5]: https://en.wikipedia.org/wiki/The_Open_Group_Architecture_Framework https://en.wikipedia.org/wiki/The_Open_Group_Architecture_Fr... [6]: https://en.wikipedia.org/wiki/Department_of_Defense_Architecture_Framework https://en.wikipedia.org/wiki/Department_of_Defense_Architec... [7]: https://en.wikipedia.org/wiki/MODAF https://en.wikipedia.org/wiki/MODAF [8]: https://en.wikipedia.org/wiki/TRAK https://en.wikipedia.org/wiki/TRAK
• doctor_eval 7y ago
  I’m a huge fan of code as design [1], so I tend to do my architecture thinking at a high level - the objects and interactions between systems - and then write clear and simple code which expresses my intention. To this end, if the code is clear then it doesn’t need to be documented heavily. 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_main.html http://www.developerdotstar.com/mag/articles/reeves_design_m... [2] https://www.goodreads.com/book/show/179133.Domain_Driven_Design https://www.goodreads.com/book/show/179133.Domain_Driven_Des...
  • j1elo 7y ago
    These slides do a good job at highlighting the important points from the DDD methodology: https://www.cs.colorado.edu/~kena/classes/5448/f12/presentation-materials/roads.pdf https://www.cs.colorado.edu/~kena/classes/5448/f12/presentat...
• Geee 7y ago
  I've used the C4 model to draw an overall system architecture (container level + external systems). https://c4model.com https://c4model.com
• jankar 7y ago
  A little known, but powerful notation for description and documentation of architecture of Information Processing Systems is FMC http://www.fmc-modeling.org/ http://www.fmc-modeling.org/ This site features a link to the Apache Modeling Project where a now outdated version of httpd was documented using this methodology.
  • jankar 7y ago
    Link to Apache Modeling Project: http://www.fmc-modeling.org/category/projects/apache/amp/Apache_Modeling_Project.html http://www.fmc-modeling.org/category/projects/apache/amp/Apa...
• EliRivers 7y ago
  I'd also have to document why certain decisions were taken. 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.
• markmiro 7y ago
  I think it's worth looking at it like another product that you produce. I like to imagine someone seeing my code for the first time and trying to make sense of it. 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