You must log in or # to comment.
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.
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.
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.
Honestly, as a newbie to Linux I think the ratio of well documented processes vs. “draw the rest of the fucking owl” is too damn high.
The rule seems to be that CLI familiarity is treated as though its self-evident. The exception is a ground-up documented process with no assumptions of end user knowledge.
If that could be resolved I think it would make the Linux desktop much more appealing to wider demographics.
That said, I’m proud to say that I’ve migrated my entire home studio over to linux and have not nuked my system yet. Yet… Fortunately I have backups set up.
Don’t forget the situations where you find a good blog post or article that you can actually follow along until halfway through you get an error that the documentation doesn’t address. So you do some research and find out that they updated the commands for one of the dependency apps, so you try to piece together the updated documents with the original post, until something else breaks and you just end up giving up out of frustration.
I write technical documentation and training materials as part of my job, and the state of most open source documentation makes me want to stab people with an ice pick.
Do you have some reading recommendations on how to write good documentation, e.g. readmes for end users?
You’re doing God’s work!
Over my career, it’s sad to see how the technical communications groups are the first to get cut because “developers should document their own code”. No, most can’t. Also, the lack of good documentation leads to churn in other areas. It’s difficult to measure it, but for those in the know, it’s painfully obvious.
Jesus, technical people are some of the worst communicators I’ve ever worked with.
It’s not necessarily their fault though. Y’know who goes into technical jobs? People who often prefer to work with machines, physical stuff, laws of nature, that’s who. And often because it’s MUCH easier than working with people, at least for them.
On top of that, soft skills are HARD. Communication is HARD. It comes easier for some, but it’s a skill like any other. It’s the technical socialites, the diplomatic devs who become the best managers and leaders, due to the rarity of their hybrid skillsets.
I’m in the middle. Just technical enough to mostly understand the devs and understand the implications of plans, and just enough soft skills to turn that into decent documentation, emails, and working with clients.
SUCKS that I’ve gotten a taste of project management and hated the absolute fuck out of it. I probably would’ve been decent at it otherwise.
“Well–well look. I already told you: I deal with the god damn customers so the engineers don’t have to. I have people skills; I am good at dealing with people. Can’t you understand that? What the hell is wrong with you people?”
