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

71–80 of 203 posts

Re: Four kinds of documentation

#71

Post by DanieleProcida »

arjenschat wrote: post #15

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 al…

That is interesting - my experience is the opposite, that how-to guides and tutorials are the most-commonly confused types of documentation. My aim is to make the serve totally different needs:

* tutorials: I'm in charge (the teacher) and I know what the new learner needs to grasp and become comfortable with so that they gain sufficient basic confidence and skills. In the tutorials, the beginner doesn't even know what questions to ask or what language to us when asking questions

* how-to guides: the user is in charge; they are able to formulate the questions, and have the basic confidence and skills. What they need from me are the recipes.

As described, it's the difference between teaching a child to cook, and a book of recipes for somebody who already knows the basics of cooking and the kitchen but wants to know how to cook a particular thing.

If you get teaching a child to cook mixed up with a book of recipes everybody concerned will have a bad time. It matters most for the child, they will never want to learn how to cook with you again.

The same go for tutorials in my experience.

Re: Four kinds of documentation

#73

Post by teknopaul »

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?

Presumption that all code is open source. The war is won :-)

Re: Four kinds of documentation

#74

Post by undreren »

Waterluvian wrote: post #63
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.

In addition to this (and going a bit off topic). I've been adding checklists to Github PR templates (it's really easy[1]) for things like, "Did you re-read the relevant API docs? Do they need to be changed?" and it helps me a ton. [1] https://help.github.com/en/articles/creating-a-pull-request-...

Checklists work so well. A kanban board has all the same qualities if used correctly :)

Re: Four kinds of documentation

#75

Post by tootie »

dtech wrote: post #31
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 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.

Re: Four kinds of documentation

#76

Post by hanniabu »

DanieleProcida wrote: post #71
arjenschat wrote: post #15

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 al…

That is interesting - my experience is the opposite, that how-to guides and tutorials are the most-commonly confused types of documentation. My aim is to make the serve totally different needs: * tutorials: I'm in charge (the teacher) and I know what the new learner needs to grasp and become comfortable with so that they gain sufficient basic confidence and skills. In the tutorials, the beginner doesn't even know wha…

The issue is that tutorials and how to guides signs like the same thing. I prefer to use getting started and how to guides.

Re: Four kinds of documentation

#77

Post by UserIsUnused »

undergrowth54 wrote: post #22
JoeAltmaier wrote: post #13

Earlier quoted context omitted.

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…

> Why is documentation standard so low? Even in companies where good documentation would raise revenue in a way that the sales team notices[1], someone still needs to write it and someone still needs to make the business case for writing it. Engineers could, but many don't. If you're passionate about good documentation, but don't think you can deliver, it would be foolish to unless someone else is doing the writing.…

>Anecdote: At age 17, I told my English Literature teacher that I wanted to write really good physics tutorials. She looked confused at me and said "Why? Thats so boring."

I laughed and then I got sad

Re: Four kinds of documentation

#79

Post by agumonkey »

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…

It's a bit of a generic issue. Until tail becomes a norm, it's hard to understand. I found embedded test/examples pretty great to quickly get the meaning of an idiom.

in python for instance:

    def tail(l):
        '''
        >>> tail([1,2,3])
        >>> [2,3]
        >>> tail([])
        >>> ValueException("undefined on []")
        '''
        # actual logic

Re: Four kinds of documentation

#80

Post by otterley »

kazinator wrote: post #69

> if the documentation is not good enough, people will not use it. Counterexamples: people use operating systems, web browsers, various "productivity apps" and games without reading a shred of documentation.

Kubernetes... (although the documentation has gotten better over the years, to the project’s credit)

Ruby on Rails as well, for the first few years of its existence.

Post reply on HN