return to table of content

Two open source projects with great architecture documentation

pbnjay
6 replies
20h47m

As a counterpoint/opportunity… what are some great open source projects (e.g well-used/adopted) that do NOT have great docs?

unclad5968
2 replies
16h1m

SDL2 docs are not amazing, but the project itself is an incredible achievement of cross platform development.

ndiddy
0 replies
6h18m

The bespoke SDL docs aren’t too good but the header files have great documentation.

iainmerrick
0 replies
7h48m

Agreed to both.

That brings Three.js to mind, that's another terrific project with patchwork docs.

spit2wind
0 replies
12h56m

Guile Scheme: https://www.gnu.org/software/guile/manual/html_node/index.ht...

It looks like it should be good. There is a lot written. However, it's extremely disjointed and unfairlt assumes readers know things. It uses terms not defined yet, or even at all. As a taste, assume you are new to lisp and scheme. Try reading the Chapter 3: Hello Scheme![1] It contains so much mind bogglingly useless information presented in the most obtuse way possible.

Okay, you might say, that's the Reference Manual, not the Tutorial[2]. The tutorial is better...except it literally doesn't explain how to run the code. Instead, it tells you to not only to get Emacs, but to also configure it with Geiser. It doesn't show you how to do that. It passes you off to other manuals. Or, to set up Dr. Racket. To be clear, running guile code is as simple as typing 'guile' which starts the interpreter.

It's very common for the documentation to hand wave away major ideas by linking elsewhere and assuming that the linked references actually explain things (they rarely do).

Anyway, I could go on. It's simply the worst documentation I've seen because it continually leads you to believe it's good. Yet, it rarely delivers the information you need.

[1] https://www.gnu.org/software/guile/manual/html_node/Hello-Sc...

[2] https://spritely.institute/static/papers/scheme-primer.html

n_plus_1_acc
0 replies
9h39m

Gradle for sure

iainmerrick
0 replies
7h51m

React, especially React Native.

There are lots of docs, and in most cases the quality at some point was good, but they're often out of date, and old versions hang around for a long time. Real world projects often use wildly different versions of React (because it's hard to keep up with the version churn) so I guess all those different doc versions are necessary.

For React Native, the docs are missing detail so you have to look at the code, and the code comments were pretty spotty and inconsistent the last time I looked.

lioeters
6 replies
21h1m

Well-written article with examples, screenshots, going into the specifics of what makes a project documentation great for users/developers/contributors.

It made me reflect on my own work and side projects, how I could improve the docs to make things easier to understand for myself and others. As I've grown as a developer, I've been writing more and more documentation, same with tests, to a point where some projects have more tests and docs than the actual code itself.

I've heard it said that writing good documentation requires a different set of skills than writing code. Sometimes a person who is not technical or focused on development can be better at explaining things. At the least it requires a different perspective, to target the human runtime.

I'll also add that automatically generated docs can be very useful, not by themselves only, but as an additional reference.

metaed
0 replies
2h57m

I take a minimalist approach. Any project goes in a single .nw file, formatted for Noweb, edited using Vim. I use a source highlighter that recognizes multiple languages in a single buffer. Noweb generates all my objects, including program text, makefiles, tests, and all documentation. Building the project is just "noweb *nw" followed by "make".

Onawa
0 replies
3h43m

nbdev is a mixture of Quarto and Jupyter and targets the exact use case you're talking about. https://nbdev.fast.ai/

ies7
1 replies
15h32m

I use concept from diataxis.fr

Diátaxis is a way of thinking about and doing documentation.

It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.
xbar
2 replies
20h56m

"The biggest deficiency in the free software community today is not in the software—it is the lack of good free documentation that we can include with the free software."

- gdb manual

mjw1007
1 replies
20h43m

When was "today" when that was written?

hn_acker
0 replies
15h59m

The gdb manual might have been quoting the essay "Why Free Software Needs Free Documentation" [1] written in 1996 [2] by someone (not confirmed to be Richard Stallman AFAICT) at the Free Software Foundation. Excerpt [1]:

The biggest deficiency in free operating systems is not in the software—it is the lack of good free manuals that we can include in these systems. Many of our most important programs do not come with full manuals. Documentation is an essential part of any software package; when an important free software package does not come with a free manual, that is a major gap. We have many such gaps today.

[1] https://www.gnu.org/philosophy/free-doc.html

[2] https://www.gnu.org/philosophy/essays-and-articles.html

eliasson
2 replies
10h20m

Antirez (redis creator) has written a good post [1] detailing his thoughts on code comments where he identifies nine type of comments used in Redis.

What surprised me was the use of "guide comments" which most people dismiss as too trivial. I agree with Antirez conclusion that they are valuable to help the reader acknowledge their understanding of the code.

[1] http://antirez.com/news/124

tacone
0 replies
10h1m

The Laravel source code is an impressive example of that.

godshatter
0 replies
4m

I like guide comments because they show intent and because if you're scanning a function in an editor where comments stand out visually then it gives you a quick recipe of what the function nominally should be doing, which helps when you're trying to come up to speed in a code base.

They are even more useful if the author hates whitespace and tries to be too clever. I spend a lot of time trying to figure out code someone else wrote and appreciate anything that can set me in the right direction when trying to figure out what a particular function does.

raybb
1 replies
10h39m

I feel like GitLab's docs have a reputation for being very good but I haven't had much need to use them myself. Would you consider their architecture docs good?

pratclot
0 replies
9h35m

Ehm, their docs are an example of a case when stackoverflow answers provide better docs than the official pages. To put it politely.

johnjago
1 replies
1d

I was particularly impressed by the first one, esbuild. The architecture documentation is so thorough—it’s something I would have loved to have for codebases I’ve worked on in the past.

Does anyone have other examples of projects with this level of architecture documentation?

chubot
0 replies
8h6m

I wonder if the diagrams were done in Figma? Diagrams are probably the #1 thing missing from most docs, and they are hard / time-consuming to make

They do look very nice

The author of esbuild was also the CTO/main author of Figma, as far as I understand

ysleepy
0 replies
17h22m

Reminds me of the "The Architecture of Open Source Applications" series.

It has some interesting insights.

https://aosabook.org/en/

tison
0 replies
18h42m

Thanks for your sharing.

I was ever working actively on Apache Kvrocks, an alternative for Redis on Flash. And we benefit a lot from Redis docs to catch up its command. In comparison, Kvrocks docs is clearly "less than awesome".

In my $DAYJOB, I convince my boss that the docs, at least the README is important, as you show the esbuild example here.

Here are two patches to improve the README of it:

* https://github.com/GreptimeTeam/greptimedb/pull/3528

* https://github.com/GreptimeTeam/greptimedb/pull/3522

That in #3522 firstly, I tried to reduce the content and "offload" the detailed docs into the doc site. And in #3528, I found that heading elements center align is still fancy and we need some short, clear introduction and advantages.

Anyway, a good product is the leading 1 and docs is the following 0. Without a good product, no good docs can be present.

tamimio
0 replies
16h18m

NixOS and ArchOS are also the first that come to my mind, I remember also there was a less known open source project and have an amazing documentation to the point I tagged it “great docs” or something, but I lost my “my pocket” bookmarks years ago and can’t remember what was the project.

lukaszkups
0 replies
6h34m

Another example of great documentation is Vue.js one [1].

[1] https://vuejs.org/

lnxg33k1
0 replies
18h46m

To stay around the topic I really love majority of changelogs of open source projects, they're great, much more professional and informative than other for-profit entities, just this week I had to offend those clowns at ING bank because despite handling people's money, would try to be funny in app changelogs instead of being informative

janpmz
0 replies
10h17m

This shows that the maintainers really care about the quality of their repository.

hn_acker
0 replies
16h17m

As footnote 1 in the featured article mentions, Redis is not open source anymore. From Redis [1]:

Redis is source-available software, available under both the Redis Source Available License v2 (RSALv2) and the Server Side Public License v1 (SSPLv1).

Redis Stack and all Redis modules created by Redis Ltd. (e.g., RediSearch, RedisJSON, RedisGraph, RedisTimeSeries, and RedisBloom) are dual-licensed under the Redis Source Available License v2 (RSALv2) and SSPL.

Redis Enterprise is closed source and requires a commercial license from Redis Ltd.

There are previous versions of Redis under the 3-clause BSD license (free and open source [2]) [1]:

Can I continue to use versions of the products that were provided under the original 3-clause BSD license?

Yes. The license change is not retroactive. This means all source code and releases prior to the change remain under the 3-clause BSD license. You may continue to use those versions indefinitely under the original license, as long as you abide by its terms and conditions.

[1] https://redis.com/legal/licenses/

[2] https://en.wikipedia.org/wiki/BSD_licenses#3-clause_license_...

gurjeet
0 replies
21h54m

Postgres project also pays great attention to detail when it comes to documentation, readme files, and code comments.

SebFender
0 replies
6h31m

Documenting projects and situations in general is so underrated. Don't need to go overboard, but a good foundation for understanding streamlines so many things in the end. Good read.