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

81–90 of 153 posts

Re: The Surprising Power of Documentation

#81

Post by SkipperCat »

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 tech was chosen, etc.

There's nothing that makes documentation more useless than when you're trying to do something like install the software but you have to dig thru piles of docs about why Postgres was chosen over MySQL. If your users or admins cant find the info they need quickly, they'll soon discard the documentation and user/system ops will go back to word of mouth knowledgeable.

I really think good companies focus on this and those who are successful really shine.

Re: The Surprising Power of Documentation

#82

Post by auggierose »

> In the words of Bukowski, "Don't do it unless it comes out of your soul like a rocket,"

Given that Bukowski said that about writing, it applies more to writing documentation, than to holding meetings. So exactly the other way around than presented in this article.

Re: The Surprising Power of Documentation

#83

Post by ponyous »

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 never start with documentation, but I find it immensely useful. Usually it starts with someone asking about something and you can just link them to the docs without having to talk to them.

Re: The Surprising Power of Documentation

#85

Post by inconceivable »

smeej wrote: post #60

All this assumes one important thing: That people will read what you put in front of them. I've been working in startups for several years now at companies of a variety of sizes, all of which were remote-first, and which (ostensibly) relied on writing to communicate. People do not read what you write. I don't know if they can't actually read fluently or if they won't, but it does not matter if I submit a bug ticket t…

whenever i run across this issue i literally just cut and paste (or screenshot selection) what i wrote before. you have to deal with the reality you are presented with, and unfortunately in this reality nobody reads a damn thing, or they skip every other line, or skip the middle n lines of a big chunk, or whatever.

Re: The Surprising Power of Documentation

#86

Post by BLanen »

eviks wrote: post #29
sarnowski wrote: post #11

Earlier quoted context omitted.

What degree of „searchable“ are you missing from apropos? https://man.openbsd.org/apropos.1

All of the basics of anything google-like: typo-friendliness with word forms and phrases, links to source, formatting of output, GUI, or not spamming the output with a dozen of lines of warnings that some man page files are missing. Then a bunch more degrees that I could know about if the tool were more usable

Yes.

I mostly use man pages when I already basically know the program and need to do specific thing.

Even then I don't use man itself but usually a webpage of the manfile because of UX.

Re: The Surprising Power of Documentation

#88

Post by Cthulhu_ »

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…

There's another category that's missing from most of the (enterprisey) companies I've worked at; procedures. Think of the result of an event storming session; consider all the steps involved in all layers of your application when a user creates a new session, or wants to do X in your application.

Ex: I work in the energy sector at the moment; because their gas/electricity usage varies across the year, there's a system in place where they pay a fixed amount per month, then they pay or get paid back the difference by the end of a contract year.

It's in the energy company's best interest that the monthly amount they pay is on par. The process to adjust this monthly amount is administrative, but in addition to that there's a huge stack of things to deal with across platforms; website, apps, back-end, support, support user interface, etc etc etc.

All the processes involved in just this aspect of the company need to be documented and drawn out as well, because else it has to be figured out from code or various people that happen to have it in their head. That's where a lot of the meeting culture comes from, because there's no one person in charge of this process, and the ones that know enough don't get together to write it down (and then maintain that documentation).

Re: The Surprising Power of Documentation

#89

Post by Cthulhu_ »

mewpmewp2 wrote: post #76
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 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.

Re: The Surprising Power of Documentation

#90

Post by alexpotato »

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"

Post reply on HN