Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Two open source projects with great architecture documentation

johnjago.com

Post reply on HN
Print view View original

11–20 of 38 posts

Re: Two open source projects with great architecture documentation

#11

Post by WillAdams »

lioeters wrote: post #4

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 h…

The tools for this should be better.

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

Re: Two open source projects with great architecture documentation

#12

Post by tamimio »

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.

Re: Two open source projects with great architecture documentation

#13

Post by hn_acker »

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

Re: Two open source projects with great architecture documentation

#14

Post by unclad5968 »

pbnjay wrote: post #6

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

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

Re: Two open source projects with great architecture documentation

#15

Post by hn_acker »

mjw1007 wrote: post #7
xbar wrote: post #5

"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

When was "today" when that was written?

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

Re: Two open source projects with great architecture documentation

#16

Post by ies7 »

lioeters wrote: post #4

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 h…

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.

Re: Two open source projects with great architecture documentation

#17

Post by remram »

ies7 wrote: post #16
lioeters wrote: post #4

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 h…

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.

https://diataxis.fr/

Re: Two open source projects with great architecture documentation

#18

Post by spit2wind »

pbnjay wrote: post #6

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

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

Re: Two open source projects with great architecture documentation

#20

Post by eliasson »

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

Post reply on HN