Hacker News new | ask | show | jobs
by pbnjay 820 days ago
As a counterpoint/opportunity… what are some great open source projects (e.g well-used/adopted) that do NOT have great docs?
5 comments

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

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

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

The bespoke SDL docs aren’t too good but the header files have great documentation.
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.

Ansible documentation is nightmarish.
Gradle for sure