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

Four kinds of documentation

divio.com

Post reply on HN
Print view View original

181–190 of 203 posts

Re: Four kinds of documentation

#181

Post by GordonS »

ergothus wrote: post #179
tootie wrote: post #75

Earlier quoted context omitted.

I've said before that the killer feature that launched Java wasn't garbage collection or checked exceptions, but javadoc. Autogenerating HTML documentation based on strictly-typed interfaces was absolute genius and I really haven't seen it topped by any modern language.

Interesting, because when I switched to Java I absolutely hated (and still do!) the autogenerated documentation. Included was every variation of the constructor. Missing was HOW I would actually call it, and where I would get the params to it. It's been the better part of a decade, so I can't actually quote correct APIs, but I recall trying to connect to an LDAP server - I just needed to call one of four constructor…

At the end of the day, it's up to the developer to provide useful documentation.

Especially in the enterprise world, I often come across completely useless code docs, created purely to satisfy SonarCloud or an otherwise stupidly dogmatic gated checkin of the "all public methods must have code docs!" variety. I'm sure many of us have come across it - code docs for a constructor that say "Constructs a Widget", or for an `AddWidget` method that says "Adds a Widget"; utterly pointless. I think of this as "dogma driven documentation".

Re: Four kinds of documentation

#182

Post by mcdevilkiller »

franciscop wrote: post #156
swinglock wrote: post #155

Earlier quoted context omitted.

franciscop/server > Powerful server for Node.js that just works so you can focus on your awesome project This is not a "quick general description of the problem the project solves" and I don't even know what the code does after reading this. You can do better than this.

Agreed, I haven't liked that line for a while. What about something like this? > A server for Node.js that works out of the box with modern Javascript It is a Node.js server with a bunch of middleware so that you don't need to do common things like body-parser, cookies, etc. It's also based around async/await instead of callback-based, which makes it easier to work with more modern JS and that prevents me from callin…

Node.js web server that bundles and configures a lot of middleware so you don't have to. Or something along the lines. Instead of hinting what is the gist of how it works, say it straight away.

Re: Four kinds of documentation

#183

Post by Shish2k »

franciscop wrote: post #114

I am not sure if it's missing or it's part of one of these four, but another very important part for me is the introduction/README. Probably the most important one. Introductions include: - Project health indicators, all green. [tests | passing] and such. - Quick general description of the problem the project solves. - A simple code snippet showing how easy it is to use it. Not the most complex way of using it as man…

One thing I always want to see in a README: what command do I type to build and run this thing :P

Re: Four kinds of documentation

#184

Post by yspeak »

franciscop wrote: post #114

I am not sure if it's missing or it's part of one of these four, but another very important part for me is the introduction/README. Probably the most important one. Introductions include: - Project health indicators, all green. [tests | passing] and such. - Quick general description of the problem the project solves. - A simple code snippet showing how easy it is to use it. Not the most complex way of using it as man…

You forgot one which is to tell what it is. I don't know how many project pages I've seen that don't tell you what it does or even give a good hint. Even after reading several pages into the documentation. It sends the message that it's only for people in the know and others are not welcome without becoming an expert in the code.

Re: Four kinds of documentation

#185

Post by bbanyc »

Back in the early days, the printed manuals for Research Unix and BSD consisted of two volumes. Volume 1 was the reference and consisted of all the man pages for every command (section 1), system call (section 2), library function (section 3), etc. Volume 2 contained longer documents - what this article calls tutorials, how-tos, and explanations.

The man command let you read all the pages in volume 1. Volume 2 only existed in print, with the troff source in /usr/doc but no obvious way to find it if you didn't know where to look. So naturally volume 2 fell by the wayside. When I was learning Unix in the late '90s and early '00s I had no idea there was supposed to be "official" documentation besides man pages, and filled in the gaps with random web tutorials and borrowed O'Reilly books and other "unofficial" sources.

Nowadays some "Unix purists" are insisting that man pages are all the documentation you could ever possibly need, and if the man page is too long that means the software is too bloated. I find that attitude to be ahistorical. Like anyone's going to learn to effectively use troff and eqn from a cut-and-dried syntax description.

(I could ramble a bit about the other documentation formats that have sprung up to replace troff and how, nice as they can be, they don't replace the convenience of manpages, but this comment is long enough.)

Re: Four kinds of documentation

#186

Post by lliamander »

bbanyc wrote: post #185

Back in the early days, the printed manuals for Research Unix and BSD consisted of two volumes. Volume 1 was the reference and consisted of all the man pages for every command (section 1), system call (section 2), library function (section 3), etc. Volume 2 contained longer documents - what this article calls tutorials, how-tos, and explanations. The man command let you read all the pages in volume 1. Volume 2 only e…

> The man command let you read all the pages in volume 1. Volume 2 only existed in print, with the troff source in /usr/doc but no obvious way to find it if you didn't know where to look. So naturally volume 2 fell by the wayside.

I guess my feeling that man pages were insufficient is not without basis.

Re: Four kinds of documentation

#187

Post by usrusr »

dtech wrote: post #131
usrusr wrote: post #119

Earlier quoted context omitted.

The problem with this family of tooling is that they are essentially fill-the-blanks forms and that all the surrounding ceremony is generated indiscriminately of wether the blanks were actually filled or not. Or worse: (pre-)filled with redundant placeholders like "@return returns the $Typename". The frustration pointed out by OP is that when you see a page of "blank" generated documentation you never know if there i…

Exatly. A "/ @return String */" is absolute garbage Javadoc, but that does not mean that the concept is bad or cannot be put to good use.

Sure. Even the most sparsely populated javadoc suddenly turns from a nightmare into a valuable improvement when you stop trying to pull information with a browser and just enjoy what the IDE presents when implementing an API client, if it is presenting something. More authored content is still better than less, but the amount of empties remaining stops being a hindrance when consumed through an opportunistic push mechanism.

Re: Four kinds of documentation

#188

Post by mark-r »

ipsi wrote: post #101
kazinator wrote: post #69

> if the documentation is not good enough, people will not use it. Counterexamples: people use operating systems, web browsers, various "productivity apps" and games without reading a shred of documentation.

Is that completely true, though? Almost all modern games include a (sometimes optional) tutorial, explaining the basics of how to play the game. Some number (a few? many? most?) of productivity apps will have in-app tutorials to get you up and running. Operating Systems... might have a tutorial? It's been a while sine I booted one up, and I'd likely skip it if present. On top of that, the GUI nature of these apps mak…

When Windows was new, Microsoft was militant about everybody sticking to the common controls. They wanted people to get used to how they operated, so that they would be able to instantly operate a new app for the first time.

Re: Four kinds of documentation

#189

Post by mark-r »

nlawalker wrote: post #122

docs.microsoft.com has a taxonomy that's a superset of this: overview, quickstart, tutorial, sample, concept, how-to, reference, resources. Most of the tables-of-contents are organized around this. Example: https://docs.microsoft.com/en-us/azure/app-service/

The only problem with Microsoft is that they delight in rearranging their web site. I'll bet that link is dead within a year.
Post reply on HN