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

17 points by digitalsanctum 3y ago ↗ HN

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?

4 comments

[ 2.4 ms ] story [ 23.2 ms ] thread

StuckDuck 3y 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 3y 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.

9wzYQbTYsAIc 3y 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.

_448 3y ago ↗

> I'm also surprised that there isn't a de facto specification...

Wasn't OMG/UML suppose to do that?