Relevant xkcd

This is why Technical Writer is a full time job.

"set all environment variables"

The mistake is the assumption of a certain level of end user knowledge.

This is why I did a “walkthrough test” when I had to write documentation on this sort of thing. I’m a terrible technical writer, so this shit is necessary for me.

I grabbed my friend who knows enough about computers to attempt this, but not enough about infrastructure to automatically know what I meant when I was too vague.

Took two revisions, but the final document was way easier to follow at the end

Reminds me of the time I asked a question about a Magic: The Gathering card tomy local game store's Facebook page. The card was Sublime Archangel. I asked what happened if it gave a creature Exalted that already had one. Someone sarcastically replied that it already says it on the card. I was a new player, how was I supposed to parse the phrase "If a creature has multiple instances of exalted, each triggers separately"? For all I knew that could mean that they didn't stack because they would need to trigger together. I didn't have the vocabulary to understand those things.

I try to remember this when explaining what I might believe are simple concepts to people because that person really upset me.

That's why blog posts rock. Most popular projects will have a dozen blog posts for different configurations. For example, when looking to set up NextCloud, I found docs for almost all combinations of the following:

• Apache and Nginx configuration
• running through Docker or directly on the host
• MariaDB and Postgres configs (and SQLite, with proper disclaimers)
• Collabora and OnlyOffice config

It does take some knowledge of each of the above if you need one of the few configs that's not available on a blog post, and some of the posts are outdated, but with a bit of searching almost everything is documented by someone on the internet.

This shouldn't be necessary (official docs should be more comprehensive), but at least it's available.

That's just sloppiness.

The information that familiarity gives you is "WTF does this field means", and it's the only thing that's actually there. How you get a value and how a value is formatted are things no amount of expertise will save you from having to tell the computer, and thus you can't just forget about.

(And let me guess, the software recommended install is a docker image?)

I don’t think it’s (just) that. It’s also a different skill set to write documentation than code, and generally in these kind of open source projects, the people who write the code end up writing the documentation. Even in some commercial projects, the engineers end up writing the docs, because the higher ups don’t see that they’re different skill sets.