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

151–160 of 203 posts

Re: Four kinds of documentation

#151

Post by qplex »

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 sentence describing what a project does (preferably the first sentence of a README)

Re: Four kinds of documentation

#152

Post by carapace »

franciscop wrote: post #125
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?

*writer

;-P

Re: Four kinds of documentation

#153

Post by simonsarris »

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…

We have a similar four-part documentation strategy: Tutorial, Technical introduction pages, Auto-generated API, and Samples

Many people hate auto-generated API documentation because library authors do not write enough of it.

For example here are my project's auto-generated documentation from source code, for two classes:

https://gojs.net/latest/api/symbols/Diagram.html

https://gojs.net/latest/api/symbols/GraphObject.html

That's 1238 words and 1408 words before you even get to the constructor.

There should be a lot of information that comes out of the auto-generated API: What it is, what to know, different kinds of classes interact, and where to go next.

Then of course a primary tutorial: https://gojs.net/latest/learn/index.html

And then conceptual Intro pages: https://gojs.net/latest/intro/index.html (62 of them, covering everything from high level concepts to printing)

Then, since so many people learn by example, hundreds of samples, organized with pictures and tags for each, with an explanation and commented code: https://gojs.net/latest/samples/index.html

Re: Four kinds of documentation

#154

Post by curryst »

protomikron wrote: post #53
ses1984 wrote: post #52

Earlier quoted context omitted.

I've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.

But what's the point then? If there's a tool, that can make "documentation" out of source code, I can just look at the source code?

The tool parses out the bits that you're interested in. If you want to know what year the proverbial apple fell on Isaac Newton's head, you can get a biography and start reading, or you can Google and let the machine filter out the irrelevant bits.

If I'm looking at documentation, I want the inputs and outputs and a brief description of what it does. I care very little about the implementation, or I would write my own.

Re: Four kinds of documentation

#155

Post by swinglock »

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…

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.

Re: Four kinds of documentation

#156

Post by franciscop »

swinglock wrote: post #155
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…

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

Re: Four kinds of documentation

#157

Post by swinglock »

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…

My first problem is that "a server" only tells me it probably listens on a socket.

Is it a web server, a web framework, a PBX, telnet or general TCP, UDP or Unix socket support functions? Which protocols does it run? Is it a library? Is it a daemon?

It says so little, it could be literally anything.

I guess it has something to do with HTTP and I guess it's a library/framework because I guess a web developer wrote this, but only because it mentions JavaScript and doesn't specify further. But these are still just guesses, I wouldn't know from the text alone.

> works out of the box with modern Javascript

Does it work with other languages too, just not out of the box? If not, the "out of the box" doesn't add anything here. Doesn't similar code work out of the box anyway?

Re: Four kinds of documentation

#158

Post by arcturus17 »

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…

Not GP but my question when I read this was “why not Express tho” and “modern JS” (as in ES6 imports etc) did click.

Re: Four kinds of documentation

#159

Post by tomcam »

protomikron wrote: post #14
Consultant32452 wrote: post #11

Earlier quoted context omitted.

I use javadocs all the time. Those are generated off comments in code. Is that the kind of thing you mean?

Yes. Now if you use human language to document your functions (methods) that is not a problem, but too often I see something like: public class BookStore { ... /** * @param book The book. * @return The price. */ public static float getPrice(Book book) { return book.price() } } No shit sherlock! I admit that this is a contrived example, but you get my point.

My favorite by far is

    y++; // Bump y
Instead of

    y++; // Do we need error checking for top of y axis?

Re: Four kinds of documentation

#160

Post by arminiusreturns »

I like this article, and if I may I'd like to add a more meta comment.

In my experience, the biggest issue is getting people to use documentation systems in the first place. For example I have absolutely grown to hate confluence. Without plugins, and even with, it's a mess that becomes a barrier instead of a conductor.

Therefor, for technical people, I think the best documentation tends to be easily accessible raw text. I personally use a combination of emacs org mode and asciidoc/asciidoctor. If I'm already always in emacs, why not use something already right there, and is quick and easy?

The structure is important, but people just need to actually write the documentation in the first place. So, just write, and you will build the skills to differentiate types as the article refers to.

Post reply on HN