Ask HN: What are great examples of high level design documentation for software?

I have over twenty years of software engineering experience and I've seen countless examples of architecture documents but I rarely see a high level design document that really stands out. I'm also surprised that there isn't a de facto specification or book that I know of.

What are good examples or templates for a high level design that you use for describing distributed systems? Is there a book or similar resource that I'm missing?

17 points | by digitalsanctum 511 days ago

3 comments

  • 9wzYQbTYsAIc 511 days ago
    This is likely not what you are looking for, but worth pointing out, as the web is a distributed system.

    https://datatracker.ietf.org/

    https://www.w3.org/standards/

    edit: Not as formalized as other documents, but you you might enjoy this high-level document: https://www.w3.org/DesignIssues/LinkedData.html

    Both IETF and W3C use strong templates for their documents and have well established processes for working groups.

  • StuckDuck 511 days ago
    I think the gnome project deserves a mention here, their docs program is really complete, and covers many high level aspects of how to use the software. Most gnome apps also use it
    [-]
    • than3 511 days ago
      That may have been true at one point, but post Gnome 2 exodus, a surface look will look like its good, but any deeper look will show its outdated.

      Its also not very maintainable/supportable, and while that is changing slowly, they've written themselves into a corner in some respects.

  • _448 510 days ago
    > I'm also surprised that there isn't a de facto specification...

    Wasn't OMG/UML suppose to do that?