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.

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

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

It has some interesting insights.

https://aosabook.org/en/

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

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?

"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

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

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_...

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.

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?

I have a repo [1] on awesome architecture docs if anyone wants more examples. It should be copied over to here [2] soon, too.

[1] https://github.com/noahbald/awesome-architecture-md [2] https://github.com/matiassingers/awesome-readme

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

[1] https://vuejs.org/

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

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.

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

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.