> Your attitude of "docs are useless" is self-fulfilling.
Yes. Of course the docs are horrible, if no one can take time to improve them, because improving them is not "real work". Spending one day fixing the wiki pages to make information easy to find, that's one wasted man-day! On the other hand, the whole team spending a few hours in meetings to clarify misunderstandings that would not happen if there was one clearly written wiki page about the topic... that's okay, because communication is important.
I think another problem is that things work bad by default whenever the "customer" is not in a position to give feedback and require improvement. Suppose the developer needs an information, and the wiki page is hard to understand. The developer is hardly in a position to request a rewrite from the author -- the author has more knowledge (about given topic) and therefore is in a stronger position. Also, the author may choose to explain verbally or in e-mail, and then the wiki remains unfixed.
Documentation doesn't suck because companies aren't using wikis right.
Documentation sucks because it's hard/impossible to do well. Every change to the code can trigger cascading changes in documentation and there's no compiler to tell you which things need to change.
I don’t know, I think wikis work great. It’s just that writing docs is a lot of work, and like people mentioned here, info decays.
People do without internal docs for the same reason they ship without tests, Pareto principle. And writing is hard work, especially if it’s meant for other people to read.
Cheap, good, and done. Pick 2.
It’s people who don’t keep expectations realistic that wind up going crazy in this industry.
If you want your company to keep nice internal docs, you can’t be cheap. You’ll have to extend deadlines. You have to tell people: I’ll have to add another week for docs and such. Usually, it’s not worth to even bring it up. Why rock the boat?
There’s also the question of how much value they bring, usually not much.
I mostly agree with the 'waste of time' except... I did work one place where it was expected that you'd update docs/wikis/etc, and that was part of the deliverable. It wasn't perfect, and there was always some stuff that was out of date, but when you found something out of date, you were expected to confirm it and update the doc as 'out of date' - ideally link to the updated page if it was possible.
This was not a perfect system - nothing is - but the culture of the group just baked this behavior in to the timeline for 'done'. When the majority of people had that expectation, it seemed to work decently. In 25 years of professional work, that's the only place I can remember seeing it done that disciplined. And... they were only around 100 folks total - not sure it could necessarily scale as they grew.
> The only thing worse than no documentation is incorrect documentation," he said. "Because no documentation means I go somewhere else to look for it. Incorrect documentation wastes my time."
Basically: yes. Some here on HN will disagree, but they are IMO wrong. Another big time-waster for users is failing to write a document intro that identifies the target audience and the document's target information goals; it sucks to get 30 pages into the document before you finally manage to figure out that it's not the document you want/need.
This is extremely hard though. It's not just some wave your magic wand around, or ask people to not be lazy anymore or something. Distilling knowledge, understanding where readers may be coming, seeing the big picture and keeping track of different moving parts, remembering and documenting their histories, all this is real work, real cognitive effort of the highest sort, on par with developing the newest feature or migrating to a new solution or whatever is seen as the "meat" of the work, as opposed to this type of lower-status "meta" work of just documenting. Often, "writing docs" is seen as junior work, something easy. Some parts are of course more straightforward, but a lot of it is very serious work that is underappreciated. And it's a vicious cycle: as long as documentation and technical writing is undervalued, smart rational actors in the company will just do the bare minimum of it and do something more visible and flashy that people do appreciate.
----
Also, I've seen internal wikis and the issue is that they tend to go stale, and people are afraid of removing information, and some people just don't know how to use a wiki and will start using it as a message board or like a Wikipedia talk page and add stuff like "Note by Joe: I'm not sure the above is still correct since the migration to XYZ. Alice should check this part", things not deleted but crossed out with strikethrough style, because "what if it will still be useful" (they don't understand the page history concept) etc. So it becomes a dump of horrible mixture of outdated and up-to-date info, where an experienced employee will tell you "oh it's in the wiki, just check it", then you go back to them that you can't find it or you found contradictory info and they tell you "ah, of course, you should ignore the page on bla bla, we should remove it soon, for this kind of thing you need to check the other page, and even though it says on top that it's 'outdated', actually this part is still valid".
The "curse of knowledge" is also very difficult to get rid of. It's really really hard to know where the reader is coming from. And what may be obvious and over-explained for one reader may feel like not enough detail or confusing to another.
Oh you're right, I was thinking of another comment in this same thread. Mea culpa!
But my criticism of your attitude stands. If this is how you responded to developers on your team making obvious suggestions about how to make documentation useful to them, then it's no wonder you've had this problem of people not reading documentation.
Again, this just isn't a problem most teams have, because there are good solutions.
I do agree with this in the end. I also think people often underestimate how challenging it is to create good docs.
I've seen this pattern often:
- Person doesn't know how to do something.
- They fumble around until they get it working.
- Once it's finally working, they write a doc about how they did it (because our "poor documentation" is a common pain point and therefore a popular problem to attack).
- If you actually search our internal docs, you find at least one other doc describing the same process.
I've seen this happen in many different contexts, even onboarding. I've seen multiple people join the company, and each one wrote down their own "onboarding painpoints" doc to hopefully help the next person, without even noticing the existence of the previous person's equivalent doc.
So again, I still agree with you. Even in these scenarios I described, I'm willing to believe that there is some way we could've structured our docs that couldn't prevented these issues. But I have no idea what it is, and seeing all the futile attempts at improving the situation makes me irk a little at armchair "poor docs"-style comments (not that that's even related. I've gone a little off topic here!)
I think the simpler answer is that most people who complain about documentation cannot improve the docs because they don't know how. If they did understand what was being explained in the documentation, they wouldn't be complaining in the first place.
It would help if people read them. I write good docs and I often wonder why, as I have to endless redirect inbound queries to the doc. It's ok for my team, they learn, but it's annoying that the whole org never reads anything.
It would be helpful to understand why you found that to be the case.
We get off-hand comments like this about the docs on occasion, and without explanation, we can't do anything to improve the docs to resolve the complaints.
We put in a ton of effort on the docs, and we think they're great. What are you missing? Did you spend the time going through and reading the docs?
The worst is when you do write up docs, there are links to the docs, but then people ask questions answered in the docs, and then fail to even really attempt to read the docs after you tell them it's in the docs.
Often people want a quick fix designed specifically for them, and do not want to read even a few pages of docs.
Investing a lot of time and trying really hard is not the same as adding a lot of value. If your users don't find value in your documentation, saying "But we spent a lot of time on it!" doesn't really change anything.
And, to be clear, I have no idea if the person you're responding to's criticism is valid. But I also know that your response does not negate their criticism at all.
I suppose you're being sarcastic but I certainly have met people with this attitude. Sometimes its not explicit or intentional either, just the lack of time/importance from the business side of things that creates a situation where things are poorly documented/understood and it creates a dependency on certain people/companies. Ultimately I feel its up to us developers to stress the importance of investing time on documentation, but also be mature enough ourselves to realise that this is part of the job.
The docs are soooooo bad. This is the same story with any exciting / new product.
Honestly, I'm beginning to think that we need some kind of documentation-first style development. Like TDD, but DDD....
I have integrated Facebook APIs, Instagram (well, same thing), Google APIs, Stripe APIs, Mailchimp APIs, etc. etc.
And the only thing common among all of them? The documentation is _terrible_..., like, _terrible_.
I also run a few products online and I spend so, so much time trying to get the documentation right. It's incredibly boring and tedious, but I really feel that if you want to set yourself apart from the big players, make good documentation. It can't be that hard.
> Unless they are not reading it, or properly paying attention. [...] Sometimes it is on the user.
If they make no effort, sure. But looking for an answer to a question and finding something that seems to works is a perfectly reasonable way to use documentation. If there's a dangerous gotcha and it isn't documented right there, then the documentation is structured badly.
> Or following an unofficial document
That could be a very clear symptom of bad documentation.
Sometimes it's on the user, but if lots of users are failing to use your documentation, maybe consider that the documentation is bad.
Yes. Of course the docs are horrible, if no one can take time to improve them, because improving them is not "real work". Spending one day fixing the wiki pages to make information easy to find, that's one wasted man-day! On the other hand, the whole team spending a few hours in meetings to clarify misunderstandings that would not happen if there was one clearly written wiki page about the topic... that's okay, because communication is important.
I think another problem is that things work bad by default whenever the "customer" is not in a position to give feedback and require improvement. Suppose the developer needs an information, and the wiki page is hard to understand. The developer is hardly in a position to request a rewrite from the author -- the author has more knowledge (about given topic) and therefore is in a stronger position. Also, the author may choose to explain verbally or in e-mail, and then the wiki remains unfixed.
reply