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

Posted by digitalsanctum on Friday December 02, 2022 @11:37AM
from the ask-hn dept.

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 | on HN )

Re:Ask HN: What are great examples of high level design docu... by StuckDuck on Friday December 02, 2022 @04:07PM (#33836921)

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

[ Parent | on HN ]

Re:Ask HN: What are great examples of high level design docu... by than3 on Friday December 02, 2022 @05:51PM (#33838063)

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.

[ Parent | on HN ]

Re:Ask HN: What are great examples of high level design docu... by 9wzYQbTYsAIc on Friday December 02, 2022 @08:18PM (#33839254)

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.

[ Parent | on HN ]

Re:Ask HN: What are great examples of high level design docu... by _448 on Saturday December 03, 2022 @07:11AM (#33842872)

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

Wasn't OMG/UML suppose to do that?

[ Parent | on HN ]