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

Ask HN: What's the best documentation you've ever read?

news.ycombinator.com

Post reply on HN
Print view View original

71–79 of 79 posts

Re: Ask HN: What's the best documentation you've ever read?

#71

Post by pasbesoin »

mjw1007 wrote: post #15

The TeXbook, and the Exim spec. 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.

Re: Ask HN: What's the best documentation you've ever read?

#72

Post by WalterGR »

kaycebasques wrote: post #67

Tech writer here. I'd be hugely thankful if you included why a given set is the best in your experience!

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

Re: Ask HN: What's the best documentation you've ever read?

#73

Post by mmt »

cellover wrote: post #23

PostgreSQL's documentation to me is a reference. 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.

Re: Ask HN: What's the best documentation you've ever read?

#74

Post by actionowl »

https://docs.saltstack.com/en/latest/topics/development/inde...

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.

Re: Ask HN: What's the best documentation you've ever read?

#75

Post by danpalmer »

spicyj wrote: post #66
danpalmer wrote: post #64

Earlier quoted context omitted.

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

Thanks! * 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 particu…

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.

This is just my 2 cents though.

Re: Ask HN: What's the best documentation you've ever read?

#76

Post by spicyj »

danpalmer wrote: post #75
spicyj wrote: post #66

Earlier quoted context omitted.

Thanks! * 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 particu…

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

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.

Re: Ask HN: What's the best documentation you've ever read?

#77

Post by sametmax »

danpalmer wrote: post #75
spicyj wrote: post #66

Earlier quoted context omitted.

Thanks! * 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 particu…

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

Making complicated things easy to understand is much more simple in python than in js though.

Re: Ask HN: What's the best documentation you've ever read?

#79

Post by kaycebasques »

WalterGR wrote: post #72
kaycebasques wrote: post #67

Tech writer here. I'd be hugely thankful if you included why a given set is the best in your experience!

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

Just saw this. Absolutely. I'll email you.

My personal is kayce@basqu.es for anyone else in the same boat.

Post reply on HN