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.
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".
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.
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.
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."
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.
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.
Readit News
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.
I wish that Literate Programming was more widespread:
http://literateprogramming.com/
Currently trying to arrive at a good toolchain for my own efforts: https://willadams.gitbook.io/design-into-3d and https://github.com/WillAdams/gcodepreview and at this time, the best option is looking like:
https://quarto.org/
and TeXshop and probably .dtx files (but if someone has a better suggestion, I'd be open to it).
> 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.
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
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.
It has some interesting insights.
https://aosabook.org/en/
Does anyone have other examples of projects with this level of architecture documentation?
They do look very nice
The author of esbuild was also the CTO/main author of Figma, as far as I understand
- gdb manual
> 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
> 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_...