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

121–130 of 203 posts

Re: Four kinds of documentation

#121

Post by anaphor »

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…

A great example of the simple code snippet is Flask https://palletsprojects.com/p/flask/

Re: Four kinds of documentation

#123

Post by peterwwillis »

There's more than four kinds; the main point should be that they need to be written with their particular purpose in mind. Here's some categories that apply just to system operations:

  - Reference
  - Discussion
  - Planning
  - Tutorial/Educational
  - How-To
  - Process Template (many, many kinds)
  - Process Implementation
  - Q&A
There are also attributes: Local/Global, Draft, Approved, Certified, Published, Restricted, Versioned, etc. There's the venue: Internal, Customer-facing, Regulatory, Quality Assurance, Development, Managerial, Executive, etc. Then there's the scope of the document: high-level, deep dive, navigation, etc.

When you write documentation, you must know your audience, what they need your document for, whether your document gives them everything they need, whether it's clear & concise, and whether anyone can find it when they need to. They should know when it was written & by whom, what it was written for, who it applies to. It should provide references to everything someone needs to know to make use of the doc. And not only should the document be clear, it has to stylistically express detail and make the document easier to process.

Re: Four kinds of documentation

#124

Post by lalaithion »

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.

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 the function, even though I got the order of the arguments wrong.

https://hoogle.haskell.org/?hoogle=Map%20k%20v%20-%3E%20(v%2...

Re: Four kinds of documentation

#125

Post by franciscop »

kaycebasques wrote: post #64

As a practicing technical writer I can testify that these content types are a common way to organize your documentation collection and identify gaps. It’s a useful exercise to list each doc as a row in a spreadsheet, and then mark whether each doc is a tutorial, guide, conceptual overview, or reference, or a confused combination. Many times you’ll see that you have explained how feature A works but have no tutorial t…

As an OSS author this is very interesting, could you share more info or references about this please?

Also I'm curious, how do you become a technical writter? Does it involve writing articles/blogposts/etc to promote the project?

Re: Four kinds of documentation

#126

Post by artursapek »

blattimwind wrote: post #112
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 docume…

> Comments should be in the code itself

Rust handles this nicely; its generated docs are based off source code comments. Same with Golang.

Re: Four kinds of documentation

#127

Post by Crinus »

pjungwir wrote: post #120
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 a…

AFAIK GNOME and KDE's help systems have the ability to view info files and there is also the tkinfo viewer i mentioned.

However note that the "source documentation system" i refer to is texinfo, not info. Texinfo is a preprocessor and documentation language (think docbook) for manuals that produces a bunch of formats, one of them being info, a text-only hypertext format (which was one of the earliest hypertext formats AFAICT). GNU info is a viewer for that format, but there are others, however all of them just view info files and have its inherent limitations (e.g. preformatted text, links using a rigid syntax, etc) - though also they have benefits such as support for topic keywords, indices, etc.

Texinfo can also be converted to other formats like PDF (through tex - i guess the initial version generated only tex and info output, thus the name texinfo) and HTML. So you wont be using texinfo to view info as PDF files, but you'd be using it to generate PDF (via tex).

I guess the "texinfo" and "info" names can be confusing and make people think that they are the same thing - the fact that AFAIK texinfo is the only info file generator (and that GNU info is called just "info" which is the same as the file format name) doesn't help :-P.

Re: Four kinds of documentation

#128

Post by weaksauce »

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 feel similar though it’s better than nothing to me. It’s feels like describing what a forest looks and operates by listing every tree in the forest. I want the higher level overview of component parts.

Re: Four kinds of documentation

#129

Post by dtech »

undreren wrote: post #41
dtech wrote: post #33

Earlier quoted context omitted.

A separate specification works much better as long as that specification is also enforced during the build. A separate openapi spec that is not enforced can quickly become outdated, then an auto-generated from code is better.

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

Re: Four kinds of documentation

#130

Post by zackmorris »

I use lack of ambiguity as a measure of documentation quality. The best (honestly the only good) documentation that I've ever found is at:

" rel="nofollow">https://www.php.net/

For example:

https://www.php.net/echo

Note how even this simple arbitrary example tells us "No additional newline is appended." It's shocking to me how many other guides would leave something that critical out of the manual.

Then there are even helpful examples beneath that showcase users' experiences and any errata that they've discovered.

Contrast this with Ruby's manual:

https://docs.ruby-lang.org/en/master/ARGF.html#method-i-prin...

I can infer that to_s is probably to_string. But I'm already hit with several new concepts like $, $_ and $\ which aren't clickable, so now it requires work to track down what they mean. The related methods beneath (like puts) are similarly cryptic. A good percentage of the time in search engine results, I click both the Ruby documentation and Stack Overflow links.

I don't remember ever really learning PHP, because I realized quickly into it that it was a thin wrapper fixing any operating system shortfalls, generally leveraging concepts and contextual cues from C, C++ and the shell. Meanwhile Ruby had one of the steepest learning curves I've ever encountered outside of functional programming, even though it's similarly based on Perl and the shell.

So where Ruby is a "convention over configuration" language, PHP is more of an "existing context over surprises" language.

Writing the documentation for a language or framework can reveal these surprises, and over time, improve the tech itself and lead to a better experience.

Post reply on HN