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

71–80 of 153 posts

Re: The Surprising Power of Documentation

#71

Post by phkahler »

CharlieDigital wrote: post #69
franciscop wrote: post #6

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation,…

> Imagine working on a codebase where 80% of the code was unused or commented out That's not documentation; that's code.

>> That's not documentation; that's code.

It's an analogy to make the point - we delete old code that's not relevant any more. Imagine reading documentation where 80 percent of it is no longer relevant but is kept around "just in case".

Re: The Surprising Power of Documentation

#72

Post by [deleted] »

lisasays wrote: post #61
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…

People do not read what you write. Then you need to move on, and find different people. Yes -- I know it's tough. The landscape out there is quite bleak, in fact. But these places, and these people do exist.

[deleted]

Re: The Surprising Power of Documentation

#73

Post by [deleted] »

phkahler wrote: post #71
CharlieDigital wrote: post #69

Earlier quoted context omitted.

> Imagine working on a codebase where 80% of the code was unused or commented out That's not documentation; that's code.

>> That's not documentation; that's code. It's an analogy to make the point - we delete old code that's not relevant any more. Imagine reading documentation where 80 percent of it is no longer relevant but is kept around "just in case".

[deleted]

Re: The Surprising Power of Documentation

#74

Post by franciscop »

johnnyanmac wrote: post #36
franciscop wrote: post #6

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation,…

>I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps* That must be nice. I've yet to work on a company where half my time wasn't trying to prod for some resource (be it internal code, a public 3rd party tool, or even the resource itself), sometimes playing a game of goose just to figure out who knows the author. I'd love too much docum…

> That must be nice

> The only thing worse than no documentation is wrong documentation

Yeah, that was the exact problem. One was a startup and when I joined it was all mostly up-to-date so it was great! But by the time I left (after 2 major migrations) most of it was out of date and a nightmare to find anything updated, any script that could still be run, etc.

Re: The Surprising Power of Documentation

#75

Post by Lutger »

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 repository containing the code on which they are stuck, or who just failed to read the extensive documentation and proceed to 1) run the code and 2) call me for help. Furthermore, I've actually caught myself doing the same more than once.

This led me to think that for a good documentation culture, the primary question should be: how are developers actually going to use and benefit from the docs? How documentation will get updated is the second question of importance, and writing documentation comes third.

Re: The Surprising Power of Documentation

#76

Post by mewpmewp2 »

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 things, but I never feel productive while doing that, I feel like I am just writing into a void.

Re: The Surprising Power of Documentation

#77

Post by inconceivable »

bambax wrote: post #10

We're currently trying to document an existing large Angular application and it's daunting. We wrote some meta-code to list all possible routes and attach components to routes (we were hoping Compodoc would help, but it doesn't work well anymore). We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on averag…

do you have usage analytics or ticket token analytics? i would document the most commonly accessed/used stuff first.

and make sure this is at least one person's actual full-time job. chances are you'll have to hire specifically for this role because nobody wants to be bait-and-switched into this job, but there are actual professionals that do this for a living.

Re: The Surprising Power of Documentation

#78

Post by zackees »

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…

[dead]

Re: The Surprising Power of Documentation

#79

Post by kwanbix »

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…

In my experience, not everybody is good at writing good documentation.

I usually see software build by brilliant engineers, people much smarter than I at building software, and the documentation sucks.

Not that is not there, but that is very difficult to understand.

It is clear to me that you can be very smart at doing certain things (for example writing software) and suck at others (writing documentation).

Re: The Surprising Power of Documentation

#80

Post by BlargMcLarg »

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…

Unfortunately, most cultures teach developers not to read. Between having barely any documentation, poor discoverability of said documentation, poor quality documentation, teaching people to 'talk at the first sign of trouble', it is only natural this is the outcome.

Now we're stuck with both a chicken-and-egg problem at most places, while in places with decent documentation, many developers still come in not reading it, discouraging any significant upkeep of existing documentation.

Post reply on HN