Yeah the documentation (if it even exists) of most projects is usually clearly written by people intimately familiar with the project and then never reviewed to make sure it makes sense for people unfamiliar with it. But writing good detailed documentation is also really hard, especially for a specialist because many nontrivial things are trivial to them and they believe what they’re writing is thorough and well explained even though it actually isn’t.
My CS major required me to take two upper division English classes and I think they helped me more in my career than my upper division CS classes. People forget that documentation is for ourselves too
I’m really thankful that I had a great English teacher in high school, and that my degree required a technical writing class. Being able to write a coherent email got me further in my career than the technical stuff I learned in college.
I think this is why the “my code documents itself” attitude appeals, even though it’s almost never enough. Most developers just can’t write, nor do they want to.
There is a case to be made that people should be a bit more well rounded in general, and not just find a specific niche.
So non-technical people should still have a decent familiarity with computers and maybe be able to do some very basic coding. And technical people should spend some time working on their written and verbal communication.
Because in both cases, it makes people more effective in their roles.
Totally agree. And I’d argue that we don’t even need technical writers. Even if all people do is correct grammar and spelling mistakes it would be helpful, let alone actually writing docs. It’s one of the easiest ways non-technical folks can get involved with open source projects.
You have to assume some level of end user knowledge, otherwise every piece of documentation would start with “What a computer does” and “How to turn your computer on.”
I’ve found the best practice is to list your assumptions at the top of the article with links to more detailed instructions.
Another case is listing a huge number of steps to do some task, without acting describing what the end goal for each set of instructions is (common in “how to” guides, and especially ones that involve a GUI).
This means that less technical users don’t really understand what is going on and are just following steps in a rote way, and it wastes the time of technical users since they probably know how to achieve each goal already.
I agree with this. When I publish my code, it is documented for someone in my field with around my level of knowledge. I assume you know DNS, I assume you know what a vector is, I assume you know what a dht is, I assume you know what O(log n) is.
I’m not writing a CS50 course, I’m helping you use the code I wrote.
Might be different for software like libre office which is supposed to be used by anyone, but most software on earth is built with other developers in mind.
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.
I’d rather have a great documentation than five different blog posts, where some of them might be outdated, wrong or insecure (and you only find out later).
But yes, they are helpful and easily available for popular software.
Okay, please point me to the blog posts that helped you with collabora/onlyoffice. Thanks have NEVER been able to get that to work with my nextcloud (currently using the Docker AIO).
Same with me. I played around with the setup a few times on my local machines. It took quite a bit to get it set up, then I saw an error after a couple of days and gave up. Its easier to just pull down the file and run it locally than use collabora.
I’m not at the same computer I used to look it up, so I don’t have my search history, but I think this one was pretty decent. I don’t use Traefik, but the rest describes the important bits w/ docker compose. I don’t know much about the AIO image though (I used separate images).
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?)
100% Agree, it feels like most documentation is written in a way that expects you to already know what it’s talking about… When it’s the documentation’s job to teach me about it.
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.
Yeah the documentation (if it even exists) of most projects is usually clearly written by people intimately familiar with the project and then never reviewed to make sure it makes sense for people unfamiliar with it. But writing good detailed documentation is also really hard, especially for a specialist because many nontrivial things are trivial to them and they believe what they’re writing is thorough and well explained even though it actually isn’t.
Relevant xkcd
Bold of you to assume I know how to read!
This is why Technical Writer is a full time job.
It’s also why the humanities are important. Stemlords who brag about not doing literature classes write terrible documentation.
My CS major required me to take two upper division English classes and I think they helped me more in my career than my upper division CS classes. People forget that documentation is for ourselves too
I’m really thankful that I had a great English teacher in high school, and that my degree required a technical writing class. Being able to write a coherent email got me further in my career than the technical stuff I learned in college.
I completely agree. Most peer feedbacks that I get mention my documentation. It has helped me so much
I think this is why the “my code documents itself” attitude appeals, even though it’s almost never enough. Most developers just can’t write, nor do they want to.
The problem with “It’s self-documenting” is that there are inevitably questions about what it says, and there’s no additional resources to pull from.
“my code documents itself” and “no, our CI system doesn’t upload the source jars to Artifactory, why?”
Maybe, just maybe, people have different strengths and weaknesses and cooperating around our differences is what makes us succeed.
If you know your weakness is writing documentation, please hire a technical writer.
That’s exactly what I’m saying, sorry if it came across somehow askew.
My point was there is no point in competing over whose job is “better”, we should be working together.
There is a case to be made that people should be a bit more well rounded in general, and not just find a specific niche.
So non-technical people should still have a decent familiarity with computers and maybe be able to do some very basic coding. And technical people should spend some time working on their written and verbal communication.
Because in both cases, it makes people more effective in their roles.
Most open source projects rely on volunteers, and few technical writers volunteer.
Totally agree. And I’d argue that we don’t even need technical writers. Even if all people do is correct grammar and spelling mistakes it would be helpful, let alone actually writing docs. It’s one of the easiest ways non-technical folks can get involved with open source projects.
Every time I get stuck on something confusing I’m a README and figure it out I try to submit a patch that makes it more explicit.
If the documentation is sufficient for the intended audience, it’s good enough.
Humanities are very important. Robots are not yet capable of flipping burgers!
Robots can definitely flip burgers.
Some can even do it twice!
“set all environment variables”
More recently its go to discord for the env…no joke.
My face actually dropped when I read this. I will be so mad if I ever encounter this live.
It sucks…and seems to be catching on. Ive seen a quite a few on GitHub that are now referencing using it instead of the issue tracker.
That is so depressing. Literally a markdown file in the repo would be a better issue tracker.
Don’t forget to run your shell over Discord!
This is cursed, but also cool. Hijack another platform for your authentication
Exclusively using Discord as a support channel should get you banned from the internet
The mistake is the assumption of a certain level of end user knowledge.
You have to assume some level of end user knowledge, otherwise every piece of documentation would start with “What a computer does” and “How to turn your computer on.”
I’ve found the best practice is to list your assumptions at the top of the article with links to more detailed instructions.
I do agree, manies have I found documentation saying “make a fresh install of Raspbian” as if I’m using the computer for this single issue
(Disclaimer: I am not running matrix on a Raspberry Pi)
Another case is listing a huge number of steps to do some task, without acting describing what the end goal for each set of instructions is (common in “how to” guides, and especially ones that involve a GUI).
This means that less technical users don’t really understand what is going on and are just following steps in a rote way, and it wastes the time of technical users since they probably know how to achieve each goal already.
It’s easy to forget what other people don’t innately know (or can intuit).
Why’s that a mistake? Not everything is built for a novice
I agree with this. When I publish my code, it is documented for someone in my field with around my level of knowledge. I assume you know DNS, I assume you know what a vector is, I assume you know what a dht is, I assume you know what O(log n) is.
I’m not writing a CS50 course, I’m helping you use the code I wrote.
Might be different for software like libre office which is supposed to be used by anyone, but most software on earth is built with other developers in mind.
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:
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.
I’d rather have a great documentation than five different blog posts, where some of them might be outdated, wrong or insecure (and you only find out later).
But yes, they are helpful and easily available for popular software.
Okay, please point me to the blog posts that helped you with collabora/onlyoffice. Thanks have NEVER been able to get that to work with my nextcloud (currently using the Docker AIO).
Same with me. I played around with the setup a few times on my local machines. It took quite a bit to get it set up, then I saw an error after a couple of days and gave up. Its easier to just pull down the file and run it locally than use collabora.
I’m not at the same computer I used to look it up, so I don’t have my search history, but I think this one was pretty decent. I don’t use Traefik, but the rest describes the important bits w/ docker compose. I don’t know much about the AIO image though (I used separate images).
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?)
100% Agree, it feels like most documentation is written in a way that expects you to already know what it’s talking about… When it’s the documentation’s job to teach me about it.
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.