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

11–20 of 203 posts

Re: Four kinds of documentation

#11

Post by Consultant32452 »

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 use javadocs all the time. Those are generated off comments in code. Is that the kind of thing you mean?

Re: Four kinds of documentation

#12

Post by workthrowaway12 »

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…

might be a swagger/openapi issue. golang for example does generated doc quite well imo. i wish other languages had the same.

Re: Four kinds of documentation

#13

Post by JoeAltmaier »

remotedeveloper wrote: post #8
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 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 and argument types. Ridiculous.

Re: Four kinds of documentation

#14

Post by protomikron »

Consultant32452 wrote: post #11
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 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.

Re: Four kinds of documentation

#15

Post by arjenschat »

What we've learned is that you can roll the how-to guides and tutorials into one. Once a users has learned how to use a service, they only need some inspiration on how to use it in different scenario's

Van der Meij, H Wrote a nice article [1] about minimalism in documentation referring to the first how-to guide (First_Minimal_Manual) [2] on how to use smalltalk for an IBM Displaywriter System (1980). This guide is all about just getting started, and if something goes totally wrong, you just reboot the machine.

People learn by doing. For new user, unfamiliar with your service, you have to reassure them that they can undo everything. This allows them to explore the system freely without any anxiety of doing something permanently wrong.

People prefer to be shown what todo instead of being told what to do. Ikea and Lego manuals for instance never tell you to put screw B1 into hole 7A in the right side of panel 14B Screenshots in your help center articles help a great deal with this. But these are hard to maintain, that is why we created Cliperado [3]

[1] https://www.utwente.nl/en/bms/ist/minimalism/

[2] https://www.utwente.nl/en/bms/ist/minimalism/displaywriter.p... (PDF)

[3] https://cliperado.com

Re: Four kinds of documentation

#17

Post by Angostura »

blakesterz wrote: post #6

"Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference." I'm a sysadmin and most of the documentation I write is... well it's for me! I do something once and I know I'll do it again, I copy and paste everything I did into our "docs" area so I can just copy and paste it again. I guess that falls under tech reference. My theor…

Presumably, someone else is writing the other 3 types of documentation for the actual users?

Re: Four kinds of documentation

#18

Post by smush »

These 4 split ideas are great. I've previously maintained a wiki for our department and the most viewed documents are always shifting from year to year. Until now, I've never been confident enough to act on the bits of information I've gotten from people who said they liked X article because Y, and now I can see that those articles are a mish-mash of the how-to and technical reference.

Now I will be able to use this as a framework for my continuing revisions, and be able to ensure that for any subject I want to be able to expect others to teach themselves to understand, I need to have the 4 quadrants ready to go.

Sidenote: I loath the excuses I hear so much these days about self-documenting code obviating the need for __any__ documentation or code comments at all. I'm always looked at like I'm a woozle for pushing back on that. I can't decide if that POV comes from laziness or a sense of denial (this is fine) but that's a rant for another submission.

Re: Four kinds of documentation

#20

Post by acidburnNSA »

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.

Yeah, I was coming to say it can be done right, and that's your point too. If you spend the time to put what a thing does, why it does it, and how it does it, with meaningful hyperlinks to related things, then the auto-collected docs can be really slick.

Maybe "auto-collected" is a better term for this than "auto-generated". I agree that auto-generated docs almost by definition don't add much. But if you go in and write narrative and have it get nicely collected into a slick hyperlinked webpage by things like doxygen and Sphinx, then that's great.

Post reply on HN