Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Surprising Power of Documentation

vadimkravcenko.com

Post reply on HN
Print view View original

91–100 of 153 posts

Re: The Surprising Power of Documentation

#91

Post by simonw »

Lutger wrote: post #75

One of the surprising difficulties of creating a good culture around documentation I found is getting people to actually read and use it. I guess the root cause of this is bad documentation itself, so developers come to not expect to find anything useful in there and just ignore it by default. I've often seen developers who spend hours fiddling on some detail that was clearly mentioned in the readme of the very same…

I think one of the most important features for documentation is that it needs to earn people's trust.

If people expect that the docs won't be comprehensive or will be out-of-date, they won't use them.

This is why I'm so keen on documentation living in the same repo as the rest of the project. That way it can be kept up-to-date with the state of the code, through a policy where PRs are only merged when they include the relevant documentation updates.

Having that policy in place really helps people learn to both write and read the documentation.

Re: The Surprising Power of Documentation

#92

Post by II2II »

c00lio wrote: post #47
cjfd wrote: post #39

Earlier quoted context omitted.

I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_h…

I am a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code. get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it ch…

To add to what you're saying:

Quite often something is not obvious or trivial to someone who is examining a piece of code or using a library for the first time because it assumes the person already understands the context.

An example of what I mean: perhaps it is because I have a background in the sciences, but I assume that most properties have units. A property such as height certainly does have units. So is get_height() returning the height in pixels, inches, meters, or something else? I have also been bitten by graphics libraries that measure distances in unexpected (to me) way. Is the radius of the arc with line thickness 'n' using the inside radius, outside radius, center line, or something else? The person writing the original code may think the developer using their code down the road can test different assumptions, yet the reality is the number of combinations to test will rarely be trivial (and that is assuming they identify the correct parameters to test).

It's at the point where I refuse to even consider using libraries that leave out documentation for obvious things. Even comments like "gets the height" raises red flags since it is a demonstration that the author did not put any thought into what they are documenting.

Re: The Surprising Power of Documentation

#93

Post by makeitdouble »

SkipperCat wrote: post #81

I can't stress this enough. Know your audience and tailor your documentation to them. You should write three types of documentation. One for users, one for admins and one about architecture. User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain te…

It could help to use more specific terminology than "docs".

If I'm properly getting your point, you think there should be user manuals, administration and maintenance procedures, and architecture specifications and/or decision records.

Re: The Surprising Power of Documentation

#94

Post by crispyambulance »

SkipperCat wrote: post #81

I can't stress this enough. Know your audience and tailor your documentation to them. You should write three types of documentation. One for users, one for admins and one about architecture. User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain te…

I agree with everything you said, especially tailoring documentation for intended purpose.

Except...

  > User docs are simple.
User docs are NOT simple. You have to put yourself into the mind of someone who is going to use your software to solve a problem which they have. That's never easy and it gets really hard, really fast, as the software grows in complexity or as your audience gets wider.

Re: The Surprising Power of Documentation

#95

Post by macintux »

Lutger wrote: post #75

One of the surprising difficulties of creating a good culture around documentation I found is getting people to actually read and use it. I guess the root cause of this is bad documentation itself, so developers come to not expect to find anything useful in there and just ignore it by default. I've often seen developers who spend hours fiddling on some detail that was clearly mentioned in the readme of the very same…

You’re indirectly pointing to two ongoing problems with docs: discoverability and findability. Can you accidentally or purposefully find what you need to know?

Re: The Surprising Power of Documentation

#96

Post by mwilliamson »

SkipperCat wrote: post #81

I can't stress this enough. Know your audience and tailor your documentation to them. You should write three types of documentation. One for users, one for admins and one about architecture. User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain te…

Reminds me of the four types of documentation that sometimes get listed: tutorials, how-to guides, technical reference and explanation. (Usual caveat of all models are wrong but some are useful.) https://documentation.divio.com/

My (perhaps overly simplistic) take would be that we should take the thinking we use on the product itself (Who's going to use it? In what context? What would they already know? And so on), and apply and adapt it to the docs as we would any other product.

Re: The Surprising Power of Documentation

#97

Post by makeitdouble »

Cthulhu_ wrote: post #89
mewpmewp2 wrote: post #76

Earlier quoted context omitted.

I admit, I rarely read documentation of anything, since I have no clue whether to trust it, so I will usually try to just follow my logical thought process of figuring out the solution or by trial and error. This also makes me bad myself at documentation, because if I don't use it I also feel internally that no one would read what I write in the first place also. Out of responsibility I will try to document shared th…

> I rarely read documentation of anything, since I have no clue whether to trust it There's another big issue with documentation; it's often a write-and-forget thing. I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified.

That happens when you have legal requirement on the documentation. The same way you have an accountant peering over and keeping track of every transaction that happens in your company.

Short of that you'll need to explain why the company is losing money because Jim didn't write a full explanation on why his "getUserIdOrNull" function returns null when the user id is not available.

Re: The Surprising Power of Documentation

#98

Post by sodapopcan »

It was mentioned in a bullet point in the article a table of contents is really, really important if you want people to read your README. This is usually a no-brainer for libraries but I'm talking about company's repos for the applications they are developing. Often the READMEs are quite long and ain't no way anyone is going to scroll through an entire README in hopes that their question might be answered.

Re: The Surprising Power of Documentation

#99

Post by remram »

alexpotato wrote: post #90
SkipperCat wrote: post #81

I can't stress this enough. Know your audience and tailor your documentation to them. You should write three types of documentation. One for users, one for admins and one about architecture. User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain te…

> You should write three types of documentation. One for users, one for admins and one about architecture. I use an airplane analogy (different order than your three above): 1. "Congratulations on purchasing your 747" 2. "This is how you replace the auxiliary power unit" 3. "This is how you survive the engine catching fire"

1 is not documenting anything, and both 1 and 3 are meant for pilots? Who are the "users" in this analogy?

Re: The Surprising Power of Documentation

#100

Post by entropyie »

I'm going to go out on a limb here and say that startups should be investing spare cycles in automation moreso than documentation. Do you want a 100 page install guide or a fully automated install script? Which one is more likely to be kept up to date? Which one is more likelybto have people notice it's out of date and fix it? Documentation is helpful, but automation is a force multiplier.
Post reply on HN