[dkarl]

I found organizing and finding documentation to be a huge problem ten years ago, not so much now with wikis having decent search. The biggest problem remaining is that it's simply hard to write good documentation, much harder than providing ad-hoc help in person or over Slack.

The reason is that every time you provide an ad-hoc explanation of how something works, you have a concrete context: a person, what they're trying to accomplish, and their understanding. You also have the opportunity to correct course as the person provides immediate feedback in the form of questions and comments. You have a high probability of eventually navigating to positive feedback and a thank-you at the end.

Writing documentation for an abstract audience is much, much harder, and as a result, you will likely hear a lot of negative feedback.

You think you've documented something really thoroughly, and then you hear that it took a recent hire two days to get through it instead of two hours. You start hearing, "This production troubleshooting task was supposed to be documented, but the new person said they had to figure most of it out for themself." WTF? What is "most of it?" You wrote down everything. So you talk to the new person and find out that even though they're a mid-level engineer, they only know Java and have never heard of jq, so for the part that requires pulling some data out of a complicated API response and feeding it to a different API, they wrote a 1000-line Java program complete with tests. You also find out that nobody told them how to make read-only calls to production APIs for troubleshooting purposes (you probably should have linked that info from your documentation) and oh my god in their quest to do this they somehow got their hands on the production API key used by one of the services. Equally horrifying and impressive. So that's what they've been doing for the last two days, because your documentation didn't anticipate the questions they had.

All of that would have become apparent in five minutes on Slack, and it could have been cleared up with a couple of links and examples, but you didn't anticipate any of it when you wrote the documentation. And that's because documentation is hard.

[thu2111]

This is definitely a part of the problem. Docs require a target audience but the brutal reality of writing for people in computing is that there is no bar and you can't assume anything at all about your readers, but if you dumb things down too much the skilled users who are more likely to appreciate docs in the first place will get exhausted and stop reading.

I tend to see docs and interactive QA as complimentary. If you can answer questions by linking to documentation it saves a lot of time.