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

121–130 of 153 posts

Re: The Surprising Power of Documentation

#121

Post by ren_engineer »

mwilliamson wrote: post #96
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), a…

the divio style docs concept got further refined by the creator with this - https://diataxis.fr/

mostly the same but some additional information for people who are interested

Re: The Surprising Power of Documentation

#122

Post by donkeybeer »

diarrhea wrote: post #12
gervwyk wrote: post #5

Earlier quoted context omitted.

It is important to add to this a culture of actually reading the docs. Kudos here to my co-founder Sam. First developer I’ve ever met that reads ALL the docs before touching a line of code. When we say let’s pick up some tech, he dives in and reads every page of doc he finds. The effect saves time and results in much much better technical decisions. You don’t get stuck in the unknown, you immediately know where to go…

I wish reading docs more or less fully was more normalised. Time and again I find myself suddenly the, or close to the subject matter expert just because I actually read the documentation of what everyone else had already been working with for years, but was new to me. I don’t consider knowing a technology or tool without that step. As you said, without it, you’re in the dark, doing guesswork. Doing that with multipl…

Whats the point in reading thousands of pages of documenation for an ephemeral and constantly changing project? In order to justify deep dives, the software itself has to be stable enough. I plan to read the entirety of the ANSI C specification for instance; it is a justified endeavour because ansi C is a stable standard with compilers implementing it for a long while. For a constantly changing project of course documenation is still important but it should be more geared toward quickly cluing you in on the specific part you are interested in, and hopefully make diffs easily presented and available.

Re: The Surprising Power of Documentation

#123

Post by Multicomp »

entropyie wrote: post #100

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.

I write automation constantly as my full time job. Documentation of how to do processes manually is definitely ripe to be automated.

But what parameters are available for the automation? Where does the automation live? How do you diagnose and improve when the automation breaks? Why did we even make this automation in the first place?

These sorts of questions are ripe for documentation. Most How style questions can be automated in one form or another. But the business process behind the automation, the context and domain knowledge around the autmation, for the humans who did not personally code it, documentation has major benefits that I think we as an industry don't value enough.

Re: The Surprising Power of Documentation

#124

Post by eschneider »

The real reason to write good (or at least minimally viable) documentation? The person who's going to need it most is Future You. When Future You has to return to a project a year after you last looked at things, you will than Past You for writing things down.

Re: The Surprising Power of Documentation

#125

Post by Multicomp »

hahnbee wrote: post #45
dschuetz wrote: post #32

While I agree that docu is important I've seen my share of garbage poured into wikis and presented as the single source of truth. It takes a lot of time and effort to make docu meaningful and useful with the outlook that it's ignored and overlooked anyways. Quality documentation is expensive, and, if one invests heavily into it there must be a clear workflow path that makes following and reviewing docu mandatory. Doc…

stale documentation is worse than no documentation

The cause of stale documentation? Not writing documentation.

According to this saying, the fix to stale documentation is (often implied) to not write documentation. Can't go stale if it doesn't exist!

The above saying is so often used as an excuse to write no documentation so much that while stale documentation can provide more acute pain than no documentation, the chronic pain of no documentation is a cure worse than the disease.

Re: The Surprising Power of Documentation

#126

Post by mike_hearn »

simonw wrote: post #91
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 th…

I've done that and still do.

It helps a bit, but only if your code reviewers are actually going to enforce the rule. It seems like most programmers simply don't like reading or writing documentation even though they can save large amounts of time for everyone by doing so. Certainly it's frustrating to be told e.g. "this thing we use can't do X" when how to do X is discussed in the thing's user guide, simply because someone didn't want to read it. I've had that experience before.

Code reviews let you force the issue for a while but it's hard to scale. Getting other people to enforce the same rules via review is difficult. Many devs will be really strict about things like unit testing and make it a point of pride, but not at all strict at all about updating docs. Other devs will learn which reviewers let them avoid writing things in English and send reviews there preferentially, or find other ways to dodge it. Fixing this via training or policy turned out to be nigh-on impossible: many people simply will not change regardless of how many times you send a code review back for missing docs. Nor will they change even when their questions are constantly being answered by a link to the docs, which they don't take as "you should be embarrassed that I had to google that for you" but rather "hey here's a helpful link, you're welcome".

Fundamentally there's a lack of shame about not reading things. It's not unique to software either. People ask questions answered by docs, or even by emails they just received, or they make bold assertions contradicted by docs they claim they've read, and when this is pointed out they just shrug it off in a way they wouldn't do if an obvious bug snuck through that should have been caught by testing. It's a cultural issue and needs to change, really.

One fix I'm experimenting with at the moment is for a Linux kernel style hierarchy of reviewers where everyone gets their own repo and they merge upwards, so there's at least clear ownership and if someone is consistently letting docs rot that becomes apparent to the ultimate TL when they do a quick eyeball of big merges.

It may also be worth experimenting with large language models. They could be given a change and asked, "given policy X, should this change have updated the documentation?" and if the LLM says yes then that gets flagged centrally for followup, for example.

Re: The Surprising Power of Documentation

#127

Post by Groxx »

entropyie wrote: post #100

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.

When the automation breaks, and it always breaks: gimme that 100 page doc please

Re: The Surprising Power of Documentation

#128

Post by NiklasBegley »

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…

Agreed on a lot of this, but I'd be cautious about saying that any kind of documentation is "simple". Especially when it comes to technical products - be they internal or external.

Technical writers train specifically to communicate complex technical topics to readers, and it's not an easy job. It requires understanding your readers, what kind of backgrounds they have, and what are they trying to achieve. This becomes especially important for documentation that is meant for your customers, where very real revenue depends on the quality of your docs.

I'm a bit biased since I'm the founder of a documentation startup [0], but tools also do play a big part. Devs often tend to enjoy writing something Markdown next to their code than going to an old wiki like Confluence that's disconnected from the engineering cycle. Choosing the right tool lowers the barrier to keeping the docs up to date.

[0]: https://www.doctave.com

Re: The Surprising Power of Documentation

#129

Post by mike_hearn »

simonw wrote: post #91
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 th…

I've done that and still do.

It helps a bit, but only if your code reviewers are actually going to enforce the rule. It seems like most programmers simply don't like reading or writing documentation even though they can save large amounts of time for everyone by doing so. Certainly it's frustrating to be told e.g. "this thing we use can't do X" when how to do X is discussed in the thing's user guide, simply because someone didn't want to read it. I've had that experience before.

Code reviews let you force the issue for a while but it's hard to scale. Getting other people to enforce the same rules via review is difficult. Many devs will be really strict about things like unit testing and make it a point of pride, but not at all strict at all about updating docs. Other devs will learn which reviewers let them avoid writing things in English and send reviews there preferentially, or find other ways to dodge it. Fixing this via training or policy turned out to be nigh-on impossible: many people simply will not change regardless of how many times you send a code review back for missing docs. Nor will they change even when their questions are constantly being answered by a link to the docs, which they don't take as "you should be embarrassed that I had to google that for you" but rather "hey here's a helpful link, you're welcome".

Fundamentally there's a lack of shame about not reading things. It's not unique to the software world either. People ask questions answered by docs, or even by emails they just received, or they make bold assertions contradicted by things they claim they read that morning, and when this is pointed out they just shrug it off in a way they wouldn't do if an obvious bug snuck through that should have been caught by testing. It's a cultural issue and needs to change, really.

It's possible AI can help here. Some people just don't want to sit down and read, but they'll ask questions, so an AI that reads the docs regularly could motivate people to write it. Or you could use them for code review enforcement by giving them changes and asking, "given policy X, should this change have updated the documentation?" and if the LLM says yes then that gets flagged centrally for followup, for example.

Re: The Surprising Power of Documentation

#130

Post by Lutger »

simonw wrote: post #91
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 th…

Exactly. Good documentation is much harder than you'd think.

I had similar policies. Also periodic reviews and especially during onboarding new devs I had them review the docs and make a list of missing points etc

Its just as important to delete out of date topics. Wrong and stale info is costly, it decreases trust and sends people in wrong directions.

edit: another obvious but surprisingly difficult thing to do is have everything in one system and make sure everything knows where to find it. Especially if your org is a bit bigger everybody will have their own systems and it'll be a big mess before you know it. But even so, within a single project I've often seen 3 to 8 'sources of truth', like trello tickets, images in onedrive, a word doc, markdown files, various propietary formats, pinnend posts in chat system, email archives, etc, etc.

Post reply on HN