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

161–170 of 203 posts

Re: Four kinds of documentation

#161

Post by meddlin »

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…

Instead of trying to over-simplify things for a nice one-liner:

> A server for Node.js that works out of the box with modern Javascript

Just give me the more verbose, but more conversational, explanation.

> 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 calling something like "express wrapper" or similar.

Sure it's more words, but I didn't have to think as much :)

Re: Four kinds of documentation

#162

Post by dredmorbius »

In my experience, it's explanations and how-to guides which are the most essential, with a comprehensive reference filling in the gaps. I've virtually always found tutorials almost completely useless.

I also have a major gripe with the guidelines for how-to guides: these should explain things, most especially where:

1. Not following the process precisely, or appropriately to circumstances will lead to major issues.

2. Where the function, significance, or mechanism of a given step is critical to understanding and correctly applying the tool.

3. Where the reason(s) for choosing amongst a set of options is helpful in making that decision.

One of the best concise distinctions between science and technology I've found is from John Stuart Mill: technology is the study of means, science is the study of causes or mechanisms. Technology tells you how and science explains why. Both are crucial to advanced understanding and use.

This doesn't mean that a cookbook approach needs to have detailed "why" explanations, but it should at least touch on these.

The other hugely useful aspect of a good cookbook is that it shows you the range of performance, capabilities, or applications of a tool. Readers can either hunt through for their specific problem (or something close enough to it to be adapted), or look through the range of applications to get new ideas for projects or products.

One of the best cookbook texts I've ever encountered is O'Reilly's Unix Power Tools, first published in the early 1990s and still relevant. Kernighan & Pike's The UNIX Programming Environment is strongly similar, and despite dating from the 1980s, and being substantially obsolete in part, remains a valuable reference.

Straight syntax guides, say, the Bash manpage, are useful, but are complex and difficult to navigate especially for a novice, and even a user with decades of experience. Tools such as vim and emacs share this problem, and whilst references can be useful for specific command or feature syntax and behaviour, do little to expose the power and capabilities of such tools. Cookbook approaches are far more useful.

Re: Four kinds of documentation

#163

Post by lhorie »

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…

That sounds like a marketing slogan, and honestly the JS ecosystem has so many of these that they've become meaningless.

What your thing looks to be is a wrapper over Node's `http` module, with a simplified API. "Powerful" is really not an appropriate adjective, since obviously your lib is limited to what the underlying Node's http module can do (and I'm going to go on a limb and guess that your library doesn't natively handle things like streaming or chunking or UPGRADE for web sockets or HTTP/2 push or N number of other things, considering you claim the library is also "simple").

Re: Four kinds of documentation

#164

Post by dredmorbius »

JoeAltmaier wrote: post #13
remotedeveloper wrote: post #8

Earlier quoted context omitted.

I work with a very large, complicated piece of software which has quite a comprehensive API but it's basically CRUD on top of a database. There is zero documentation about what happens when you update an object - only OpenAPI. To find that out, you would have to dig in to the database triggers. Half of working with it is trial-and-error and the other half is hope-and-pray.

Same here. Why is documentation standard so low? Tell me how that buffer management works (do I provide it? delete it? when? how?); how threading is supported (reentrant? send/receive at the same time/different threads? interprocess?); dependencies (necessary initialization? teardown? states in between?); efficiency (can I hold a lock around the call? does it block?). Instead, we often get nothing but a method name a…

Another (possible) factor driving this is service- and support-based business models.

Good documentation, enabling user self-support, eats both cost and revenue.

(To what extent this is a conscious strategey and not simply decades-of-experience-born cynicism, I'm not entirely sure.)

Re: Four kinds of documentation

#165

Post by dredmorbius »

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…

That should be the introduction (or other elements of) the Explanation, possibly of the Reference.

These suggestions generally correspond to document sections within the Linux Documentation Project HOWTOs, as an example.

Re: Four kinds of documentation

#166

Post by undreren »

dtech wrote: post #129
undreren wrote: post #41

Earlier quoted context omitted.

You can add two new columns to your Kanban board called "Documentation" and "Documentation Review". Then tasks cannot move to your "Done" column unless documentation is written and passes review. If you enforce column limits documentation it will also block other tasks if not completed.

I have about as much confidence that is gonna work as I'd have in a (non-automated) "Test" and "Test review" column

Cool.

Re: Four kinds of documentation

#167

Post by dragonwriter »

the_af wrote: post #34
michannne wrote: post #24

Earlier quoted context omitted.

Because docs take time to write, and good docs require a passionate dev who cares to write them

...plus they tend to get outdated and out of sync with the code pretty fast!

Not if the first step of updating the code is updating the documentation to reflect the intended state after the code update, preferably with embedded doctests that form part of the definition of done for the code changes.

Sure, if documentation is treated as an afterthought it tends to reflect that attitude.

Re: Four kinds of documentation

#168

Post by SamuelAdams »

xtiansimon wrote: post #40
protomikron wrote: post #5

My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated. Some time ago Swagger (nowadays OpenAPI) got really popular and many projects "had an API" and pointed users to their green autogenerated API documentation clusterfuck. When time went on this green page would become an indicator for me, that the…

I've been trying to get my head around a particular Swagger project. Here is a funny email exchange from my request for documentation: ... Hi, I reaching out to to ask if I could get my hands on some documentation because the API is somewhat a black box to me. ... The api documentation for [product] can be found here: https://api.[product].com/ ... Sorry. That's not what I mean by "documentation". It's certainly non-…

Isn't that the point of an API though? To be a black box? The example you provide is fairly simple: you hit these endpoints and get this kind of data.

If you need to add data to one endpoint and see how that travels to other endpoints, that makes sense as to why you want documentation. In that case, a product / API tutorial or recipe (like the author suggests) might be useful.

Re: Four kinds of documentation

#169

Post by the_af »

dragonwriter wrote: post #167
the_af wrote: post #34

Earlier quoted context omitted.

...plus they tend to get outdated and out of sync with the code pretty fast!

Not if the first step of updating the code is updating the documentation to reflect the intended state after the code update, preferably with embedded doctests that form part of the definition of done for the code changes. Sure, if documentation is treated as an afterthought it tends to reflect that attitude.

> documentation is treated as an afterthought

Bingo.

Do note that people here on HN live in a bubble where, for example, writing tests (any tests, not even good tests) is a given. But out there in the world there's plenty of software coding, a lot of it in major companies, where developers think testing is some cute but useless thing they teach you in college and which can be safely skipped, and managers are completely oblivious about this. Same with writing useful documentation.

Re: Four kinds of documentation

#170

Post by marcosdumay »

rovolo wrote: post #138
lalaithion wrote: post #124

Earlier quoted context omitted.

This is also a great feature of Haskell, especially Hoogle, which is what I miss the most when working in Java. If I want to find a function which, say, removes items from a Map based on a function over values, in Java I have to look and see if it's in the Map class. Nope. Is it in Guava Maps? Ah, there it is, "filterValues". In Hoogle, I can type `Map k v -> (v -> Bool) -> Map k v` into the search bar, and it finds…

I'm impressed. Being able to search for functionality by the function signature seems incredibly useful. In the "Verb-Noun vs Noun-Verb" thread from a couple days ago [0], people were saying that OO languages make autocomplete much easier because you start with the parameter you're operating on. But, autocomplete (at least in IntelliJ) only lets you search by method name. There have been lots of times where I want to…

If you try, you'll discover it is much less useful in Java. That's probably the reason it's not available there.

Pure languages get a lot of hate, but this is the kind of thing you get when you enable better static analysis of your code.

Post reply on HN