This is why Technical Writer is a full time job.
Comment on What self hosting feels like (It's painful, please help 🥲)
ExcessShiv@lemmy.dbzer0.com 1 month ago
Yeah the documentation (if it even exists) 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.
teft@lemmy.world 1 month ago
Semi_Hemi_Demigod@lemmy.world 1 month ago
It’s also why the humanities are important. Stemlords who brag about not doing literature classes write terrible documentation.
AlexWIWA@lemmy.ml 1 month ago
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
Semi_Hemi_Demigod@lemmy.world 1 month ago
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.
floofloof@lemmy.ca 1 month ago
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.
Semi_Hemi_Demigod@lemmy.world 1 month ago
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.
JackbyDev@programming.dev 1 month ago
“my code documents itself” and “no, our CI system doesn’t upload the source jars to Artifactory, why?”
HK65@sopuli.xyz 1 month ago
Maybe, just maybe, people have different strengths and weaknesses and cooperating around our differences is what makes us succeed.
Semi_Hemi_Demigod@lemmy.world 1 month ago
If you know your weakness is writing documentation, please hire a technical writer.
AlexWIWA@lemmy.ml 1 month ago
“set all environment variables”
mesamunefire@lemmy.world 1 month ago
More recently its go to discord for the env…no joke.
AlexWIWA@lemmy.ml 1 month ago
My face actually dropped when I read this. I will be so mad if I ever encounter this live.
mesamunefire@lemmy.world 1 month ago
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.
AstralPath@lemmy.ca 1 month ago
The mistake is the assumption of a certain level of end user knowledge.
Semi_Hemi_Demigod@lemmy.world 1 month ago
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.
Flax_vert@feddit.uk 1 month ago
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)
vividspecter@lemm.ee 1 month ago
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.
GBU_28@lemm.ee 1 month ago
Why’s that a mistake? Not everything is built for a novice
bl_r@lemmy.dbzer0.com 1 month ago
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
sugar_in_your_tea@sh.itjust.works 1 month ago
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.
cron@feddit.org 1 month ago
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.
harsh3466@lemmy.ml 1 month ago
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).
mesamunefire@lemmy.world 1 month ago
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.
sugar_in_your_tea@sh.itjust.works 1 month ago
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).
JackbyDev@programming.dev 1 month ago
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.
hperrin@lemmy.world 1 month ago
I don’t think it’s (just) that. It’s also a different skill set to write documentation that it is to write 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.
marcos@lemmy.world 1 month ago
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?)
SexualPolytope@lemmy.sdf.org 1 month ago
Relevant xkcd
wick@lemm.ee 1 month ago
Bold of you to assume I know how to read!