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

111–120 of 203 posts

Re: Four kinds of documentation

#111

Post by _fbpt »

harimau777 wrote: post #36

My experience has been that having names for things makes it easier to think and communicate about them; including in documentation. For example, once I learned the term "tail" I no longer had to say "every element except for the first one". As another example, learning about "complete" versus "partial" functions gave me the vocabulary to better understand and communicate about certain types of errors. Does anyone kn…

I find "first" and "rest" to be better names for "first element" and "all but first element". Whereas "head" and "tail" sound like the same type of variable, but are different types (element vs list of element).

Re: Four kinds of documentation

#112

Post by blattimwind »

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…

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

For most applications this approach is generally useless and should not be used. Comments should be in the code itself, and you expect people who want to work on the application to read at least some of the code. I.e. no reference / API documentation for applications, instead high level overview (where is what, application architecture etc.) and guides (how to set up your dev environment, how to contribute, how to prepare releases etc.).

For libraries it often makes sense to generate a reference documentation from the code itself. The drawback is that the strictly formulaic nature of comments parsed by the documentation generator has to be always kept in mind when writing the code itself. I.e. the comments need to make sense and be comprehensive when you remove them from the code surrounding them.

Some modules in the Python standard library are a good example of this. Quite a large amount of prose, separate from the code, and then a reference section generated from code. However, many modules have pretty bad documentation, where even the reference is missing crucial information (quite often very basic things like what a function returns).

Re: Four kinds of documentation

#113

Post by commandlinefan »

roelschroeven wrote: post #106
commandlinefan wrote: post #60

What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is, say, Angular better than plain-old Javascript? How is Spark better than a shell script triggered by a cron job? How is Spring better than Java by itself? What sorts of problems are they most appropriate for? Sometimes I suspect that I can’t find this informatio…

Webpages of many many projects do this very badly. I mostly resort to reading the corresponding wikipedia articles, if any, which often are clearer about what the project does and how it relates/compares to other projects.

> Webpages

I've had hit or miss success even when I drop $50 on an O'Reilly book on the topic.

Re: Four kinds of documentation

#114

Post by franciscop »

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 many do, please.

- Screenshots and gifs if it's UI-related. Very important if it's UI-related.

- Quick installation guide if using a common way, or a link to an in-depth guide if it's not easy to install.

- Links to other parts, in-depth articles, etc.

Some examples where I think I got it right (feedback welcome!): https://github.com/franciscop/server https://github.com/franciscop/ola

That said, good documentation takes a lot of effort and time.

Re: Four kinds of documentation

#115

Post by jerf »

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 have some Swagger-based documentation for a few APIs I've written, and I find it very frustrating because you can see in the renderers for Swagger that nobody actually documents with it. Nominally, several of the fields are specified as Markdown, allowing for useful formatting in your documentation, but what fields are actually rendered as Markdown in a given renderer is semi-random. The top-level description usually is, but a lot of the other fields come out random. In the worst cases, not only is the "Markdown" content rendered as plain text, it also is simply slapped between

, so the newlines are eliminated.

Re: Four kinds of documentation

#116

Post by franciscop »

Good documentation IMO strongly depends on the project scope. There are many small projects that benefit from having a single, well structured long readme because it's easier to read+use. But there are some other projects that really need the longer format and everything described in this article.

Re: Four kinds of documentation

#117

Post by slx26 »

this is a great summary. I also like to add proper information about the context, the required knowledge to tackle each part, and the goal of that part of the documentation itself. in most cases, you can write a couple lines at the start of a document saying: "this document explains A. you will be interested on it if B. you should already know about C and D before proceeding. otherwise, you might be interested on E or F instead."

I also noticed an interesting situation when trying to write good documentation: if you start too early, you will have to update it and change it a billion times (both writing the docs and testing the systems will reveal a lot of parts that can be improved). but if you start too late, everything will seem to be ok until you try to write it down. when you have done a few high-level overviews and detailed technical references, that always reveals how the are a number of important parts that could be simpler and/or more harmonic. we always try to make code simpler, but sometimes we only discover simpler ways to express things when we are thinking about them in natural language. or the other way around. perspective++

Re: Four kinds of documentation

#118

Post by franciscop »

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 have experimented with some tools to generate 3rd party docs for quick reference (didn't get far though). Not for my projects, but to analyze 3rd party project APIs.

Why do you think it's useless? What part is useless? I am considering taking on this project at some point in the future.

Edit: also I am referring to a library's API while I think you refer to a RESTful API. Would your comment also apply to libraries's API?

Re: Four kinds of documentation

#119

Post by usrusr »

tootie wrote: post #75
dtech wrote: post #31

Earlier quoted context omitted.

I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. This does of course require human-readable description in all the endpoints. But that's the same as only an autogenerated function signature in code documentation vs an added human-readable description.

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.

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 is valuable information waiting for you maybe just one or two clicks away or if it's placeholders all the way down. Consuming a sparsely filled doc almost feels like being trapped in an illustration of the halting problem.

A javadoc/-like implementation that somehow put the actually authored subset into the spotlight while not completely skipping the inferred bits could be very valuable.

(also: a javadoc/-like compiler that detects as much delegation as possible and aggressively pulls in stronger documentation when it is available further up or down the call nesting)

Re: Four kinds of documentation

#120

Post by pjungwir »

Crinus wrote: post #7

This is a nice article (though i think a bit too wordy). Note that what it calls "tutorial", "how-to guides" and "explanation" is sometimes called "guides", "howtos" and "rationale". As an application of this, I always thought that the Windows API help, especially those around Win3.1/95 had one of the better approaches for an API/library: the API is split in functional parts/groups (windows, fonts, messages, fonts, c…

> most disagreements come from the default GNU info viewer, not the source documentation system that allows for HTML and PDF output

Do you know if there's a way to access info documentation in a PDF reader (or failing that a browser)? I often try to read the info pages then quickly give up because I don't want to fuss with the navigation. I would love to be able to say `info --format=pdf --open-with=evince sed`. Is anything like that possible?

EDIT: Another cool approach that would preserve hyperlinks would be a command that starts a local web server on say 4400 and launches firefox on its index.html.

Post reply on HN