It has to be the scikit-learn documentation (http://scikit-learn.org/). Not only its great in terms of proper code documentations with a ton of examples, but it also explains the theory behind each algorithm. You can literally learn Machine Learning just by reading the docs
The thing I love about Django’s documentation is the layering. From beginner tutorial through to high level overviews of the subsystems, through to detailed usage for the subsystems, through to API level docs, through to the source code - all of it is there, and all linked together well. On top of that, it’s all well written, approachable, full of notes and caveats/warnings where necessary (for the level of the documentation too).
I’ve not seen another set of documentation that provides something at each of those layers.
The warning and caveat are the best part for me. The django team understands very well the principle of least surprise, which is why old django installs still work, the ecosystem is very well intagrated and updates are not dreaded. It strikes menthat something new like react is in version 16 (and the doc sucks) while django is much older and only reaching v2, with great docs.
I don't use React much, but from a quick look at your docs now it looks like they are much better than last time I saw them, and I can't find any major points of criticism.
I like the fact that you have the separation between getting started/tutorials, main concepts, advanced concepts, and an API reference. The notes/caveats/etc seem reasonable.
It would be nice to link to the source in the API reference, and there are a lot of mentions of APIs that could be linked (pretty much any function name in a body of text could be linked I think), but apart from that these docs look great.
That said, I haven't had to use them day after day for 6 years like I have with the Django documentation!
One thing you might want to consider for the future would be switching between versions of React. Django has a version switcher at the bottom of the screen that lets you jump between versions, shows banners when reading the docs for unreleased/insecure/old versions (in case users are linked to them), and also mentions when APIs were added in recent versions in the text.
* Links to source: I use these frequently in other libraries, but I don't think this would be as useful for React, because we tend to have just a few functions each with a complicated implementation (vs programming stdlibs or other frameworks where many methods are on the order of 10-100 lines calling other public functions). Also our implementation isn't that easy to understand. I wonder if you had a particular use case in mind?
* Linked method names: Good idea.
* Version switcher: We've thought about this and will probably add it at some point.
Not wanting to open a can of worms, and I haven't read any of the React source, but if the source isn't that useful I'd suggest the answer might be to make the code easier to understand. Developers often need to dive into the code they are using for more detailed analysis of undocumented edge cases, tracking down bugs in their own code, etc, and having an understandable framework or library is fairly critical for that.
Django does a lot of complex/clever stuff under the hood, but the source is still readable, and in most cases fairly easy to understand.
Yes, making the source easy to understand is definitely valuable (even if only for our own team's understanding).
I believe Django's "functionality/(API surface)" quotient is still much lower than React's, which means it's easier to make the source useful to a newcomer.
You should start with a very long, nicely sliced in small chunks, tutorial begining with script tags and react.create element, followed by a step by step ramp up to babel/webpack integration and only end by demonstrating create-react-app as a way to do all that automatically and more.
Not the other way around.
I get the wow effect is sexy, but it's pedagogically backward. Or at least just use it to show off, then use the momentum to motivate the reader to start from scratch.
The hello world should just say hello, and how the same code in pure html, and then in vanilla js.
Also, while progressing, you needgo from tighly coupled monolitic components to clean reusable decoupled ones, illustrating common patterns little by little.
Yes, it's tempting to do it correctly the first time, and faster. But it's mixing several things to learn at the same time, which makes things a lot harder to grasp.
At last, the tutorial should start using es5, and introduce new es6, 7, and stage 3 stuff on the way, next to the matching babel config and typical use cases. Particularly imports, spread, arrow function and destructuring. You must understand: this week i was hired to give yet another react training. The students didn't even know what the dom was. It's very common.
A bigger app than a todo list should be achieved in the end, and it should, in it's very final state have an opiniated by the book ajax and router setup, plus a friendly way to share the state without going full blown flux. Then conclude, opening to other options, including but not limiting to a word on redux and mobx.
Yes, a good doc write about other tech. It's irritating, i understand. It's not your job after all. But django has a section explaining how to configure nginx and apache. They get that it's part of the experience.
A separate section should be dedicated to integration with popular frameworks in other languages such as ror or django.
All in all, it should not assume people are advanced js dev nor that they are familiar with the js ecosystem. Many new comers come from other languages and run npm for the first time.
This would make the official tutorial 10 times larger at the minimum. It's a good thing, but people looking for a quick reference would be annoyed. So you also need to keep the current version around, which is the short story and is great when you already know what you are looking at. And make explanations about js and its ecosystem in optional sections to avoid borring people that already know the stuff.
Two more additions are nessary.
One is a glossary you should hyperlink from everywhere in the doc.
Two are schemas showing off things like data flow, components life cycle, relation between the dom and virtual dom and rendering, main functions mapped to main use cases, etc.
It's a lot of work, i known. I wrote tons of those. It takes months. But that's the only way to get a great doc. Besides, react is not a simple tech despite what every tutorial says, and a lot of magic hide the "it's just javascripy" so people get confusew.
Jekyll because it's beautiful and the user can read all the pages at once with the previous/next buttons (at the bottom) https://jekyllrb.com/docs/home/
I learned a lot from the SQLite documentation. It's not only very thorough, but it's full of insightful bits of information that is not strictly necessary but which gives a deeper understanding of the engine.
It was also the first time I encountered the flow diagram type of syntax explanation which I found to be a fantastic way to grasp the details of each command. Eg https://sqlite.org/lang_createtable.html.
I always feel like the author is my buddy talking to me. Sometime i have a question, then read one. There is it, the answer.
And this applies to the vue API as well. The guy just crafted in so many little things to make real life easiser. The event.once helper for example. Simple, elegant, useful.
Complex concepts are told in a very simple and concise fashion. There is just the right amount of text for what is told, it does not make you feel dumb and instead invites you to dig deeper in a very welcoming manner.
I even suggest it as a good way to learn about relational databases, in general.
The only downside is if the reader is "spoiled" by a particular feature that's documented as standard (such as to comply with one) and subsequently has to work with one that lacks it or implements it less completely.
The thing the latter gets right is that, as well as the usual long list of options with an explanation of what their effects are, it also describes in full detail what the program actually does, rather than leaving you to deduce it from the options.
So each option is normally described twice: once in an alphabetical list, and once where the operation it affects is described.
I remember the TeXbook, from back when it came out (more or less). One of those books that tells you what's going on, provides a very good summary of its context, and makes you want to read it.
More documentation back then seemed to be of higher caliber, than much if not most of what we wade through, today.
I think the people writing it had more time and resources for attention to detail. And perhaps more need. There was no generally public Internet for updates and corrections including turning your product from a pain in the ass quasi-brick to something useful. You had to get it right, up front.
EDIT: It all depends on how you set the bar, though. There are plenty of projects whose entire documentation is a README with a few examples.
Also, what's "best", documentation that greatly explains a horrible, unintuitive interface of a program or one that hardly needs to exist because the use of the program is so intuitive, you don't need documentation? Greater effort was spent in the former, but you understand the program better in the latter.
The tutorial is OK-ish, but the reference docs are weak. If I have a specific question about some detail of the language, the answer is very rarely there.
Sometimes the answer is written up in the bug-tracking system or an RFC. They don't seem to have a culture where someone making a behaviour change, or a language-definition decision, is expected to update the reference manual at the same time.
Please file bugs against the reference when you have these kinds of questions, it really helps.
> they don’t seem to have a culture
We actually do have that as a literal rule [1], but since we’ve started from a place where the reference is incomplete, we can’t block everything on fully filling out every last detail. It’s being actively worked on though!
1: the rule has been slightly relaxed in the last few months for reasons; now a bug must be filed, rather than writing out the literal text. They usually get done fairy shortly after though.
Gives you examples right off the bat to get started, is organized well so it's easy to dive deeper, and the author includes some conventions for incorporating the module into your app.
But as jolmg pointed out, some projects are just simple readme and that is more than enough. Love those. But the total opposite is also common, a wall of text that is meaningless and in the end, you have to go through the source code to get some answers...
Qt had amazing documentation around Qt 4.5. It's still really well-written—especially the old stuff—but their biggest problem is that they're awful at maintaining websites. The expected lifespan of a link to a page in their documentation is about two years.
I found some bugs and I wanted to fix them. I've done a little python in the past but I'm not entirely up to speed on the whole python ecosystem. This documentation was exceptional and allowed me to get my bugs fixed, some unit tests written and PR's merged.
I really like the elasticsearch docs. They seem to cover everything, it's easy to find what you're looking for, and they contain a lot of detail! the feature where you can switch ES version without leaving the page you're on is a nice touch too :)
It's gotta be emacs for me. C-h o, and helm-apropos make it super easy to investigate anything in the system. And the help pages link back to the source code (though this isn't unique to emacs) The online docs aren't bad either.
Probably the Gentoo Linux documentation. Not sure how it looks like today, but back in 2005 when I started using Gentoo it helped me a lot because not only was comprehensive but also deep enough albeit clear.
Laravel by far my favorite framework, but their docs aren't perfect, there's a lot of things I've needed to do, that just aren't in the docs, they're in the API though.
Everything in the api, should be covered somewhere in the docs with examples and use cases, imho.
I used to think this, but from a recent project with them we found them to be lacking some significant details, and generally fairly shallow. We had to contact support for a lot of clarification, and that took a while with the back and forth.
(Off-topic: I'm considering a career change from software engineering to tech writing. I'd love to pick your brain about the field. There's no contact info in your profile, but I'm waltergr@gmail.com. Thanks for the consideration.)
Wow. We had totally different experience with it then. To me it has always been simple and straight forward. Also the go tour was great to get started with the language.
