3 ms·

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

by pbnjay 3y ago

allarm 3y ago
Ansible documentation is nightmarish.
unclad5968 3y ago
SDL2 docs are not amazing, but the project itself is an incredible achievement of cross platform development.
- iainmerrick 3y ago
  Agreed to both. That brings Three.js to mind, that's another terrific project with patchwork docs.
- ndiddy 3y ago
  The bespoke SDL docs aren’t too good but the header files have great documentation.
spit2wind 3y ago
Guile Scheme: https://www.gnu.org/software/guile/manual/html_node/index.html 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-Scheme_0021.html https://www.gnu.org/software/guile/manual/html_node/Hello-Sc... [2] https://spritely.institute/static/papers/scheme-primer.html https://spritely.institute/static/papers/scheme-primer.html
n_plus_1_acc 3y ago
Gradle for sure
iainmerrick 3y ago
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.

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

by pbnjay 3y ago

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

allarm 3y ago

Ansible documentation is nightmarish.

unclad5968 3y ago

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

iainmerrick 3y ago
Agreed to both. That brings Three.js to mind, that's another terrific project with patchwork docs.
ndiddy 3y ago
The bespoke SDL docs aren’t too good but the header files have great documentation.

spit2wind 3y ago

Guile Scheme: https://www.gnu.org/software/guile/manual/html_node/index.html 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-Scheme_0021.html https://www.gnu.org/software/guile/manual/html_node/Hello-Sc... [2] https://spritely.institute/static/papers/scheme-primer.html https://spritely.institute/static/papers/scheme-primer.html

n_plus_1_acc 3y ago

Gradle for sure

iainmerrick 3y ago

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.