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.
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.
Do you have some reading recommendations on how to write good documentation, e.g. readmes for end users?
Yes. Here: "1.You arenāt writing an SOP for smart or even capable people., every. Single. Person. Needs their hand held all the way through every step regardless of technical skill. "
ā2.if you didnt state it needed to be done in the SOP, it will not be done when the end user follows the SOPā
ā3.MAKE someone else run through your SOP without you being involved. If they can successfully achieve what they needed using your SOP > congrats. If not > fix the errors that brought you to this mess.ā
ā4. Everyone is fucking stupid, be clear, and verbose.ā Weāre talking about where the start menu is, clicking on the āOKā for prompts, how to spell and type things out.
Change my given values per SOP and what itās for. But those are my main tenants.
In elemental school we had to write instructions on how to make a pb&j sandwich. The teacher then acted out your instructions literally, without adding or removing a step. I donāt think there was a single sandwich made that day.
Excellent notes. If I could add anything it would be on number 4 ā just. add. imagery. For the love of your chosen deity, learn the shortcut for a screenshot on your OS. Use it like itās astro glide and youāre trying to get a Cadillac into a dog house.
The little red circles or arrows you add in your chosen editing software will do more to convey a point than writing a paragraph on how to get to the right menu.
Iāll see about digging up recommendations if I can, but Iām on my phone right now.
My biggest single piece of advice would be this: Understand that your reader does not share your context.
What this means is that you have to question your assumptions. Ask yourself, is this something everyone knows, or something only I know? Is this something thatās an accepted standard, or is it simply my personal default? If it is an accepted standard, how widely can I assume that accepted standard is known?
A really common example of this in self-hosting is poorly documented Docker instructions. A lot of projects suffer from either a lack of instructions for Docker deployment, because they assume that anyone deploying the project has spent 200 hours learning the specifics of chroot and namespaces and can build their own OCI runtime from scratch, or needlessly precise Docker instructions built around one hyper-specific deployment method that completely break when you try to use them in a slightly different context.
A particularly important element of this is explaining the choices youāre making as you make them. For example a lot of self-hosted projects will include a compose file, but will refuse to in any way discuss what elements are required, and what elements are customisable. Someone who knows enough about Docker, and has lots of other detailed knowledge about the Linux file system, networking, etc, can generally puzzle it out for themselves, but most people arenāt going to be coming in with that kind of knowledge. The problem is that programmers do have that knowledge, and as the Xkcd comic says, even when they try to compensate for it they still vastly overestimate how much everyone else knows.
OK, I said Iād try for examples later, but while writing this one did come to mind. Haugeneās transmission-openvpn container implementation has absolutely incredible documentation. Like, this is top tier, absolutely how to do it; https://haugene.github.io/docker-transmission-openvpn/
Starts off with a section that every doc should include; what this does and how it does it. Then goes into specific steps, with, wonder of wonders, notes on what assumptions theyāve made and what things you might want to change. And then, most importantly, detailed instructions on every single configuration option, what it does, and how to set it correctly, including a written example for every single option. Absolutely beautiful. Making docs like this is more work, for sure, but it makes your project - even something like this thatās just implementing other peopleās apps in a container - a thousand times more usable.
(Iāve focused on docker in all my examples here, but all of this applies to non-containerized apps too)
Yes @Voroxpete@sh.itjust.works, please do share recommendations
Well a good indicator is if I have to check the source code of a packaged program to understand what something does, the documentation is not good enough. And yes Iāve had to do this far too much.
have to check the source code
Use the source, Luke.
But yeah: disappointing. I just swapped out my Chef ZFS module because, looking at the source, it was incomplete in ways I didnāt want to rat-hole and extend while this other two-piece kit was there.
I should use the source earlier.
as a chronic documentation reader, the best advice i can give is to document everything Anything that the user can and will potentially interact with, should be extensively documented, including syntax and behavior. Write it like youāre coming back to the project in 5 years after having done nothing and you want to be able to skip right to using it. When we build something ourselves, we often hold a bit of internal knowledge from the design process that never quite goes away, so itās almost always a lot easier for us to reverse engineer something weāve made, than it is for someone else with zero fore-knowledge to do it themselves.
Generally this can be a bit of a nightmare, but if you minimize the user facing segment itās not all that bad, because itās usually pretty minimal, and what would otherwise be a handful of pages, turns into 10 or maybe 15.
as for existing documentation, the i3wm user guide is really good, itās pretty minimalist but it leaves you enough to be able to manage.
as a chronic documentation reader, the best advice i can give is to document everything Anything that the user can and will potentially interact with, should be extensively documented, including syntax and behavior.
I donāt know about that. Iāve read some terrible documentation that had everything under the sun. Right now in the library Iām using, the documentation has every available class, every single method, what itās purpose.
But how to actually use the damn thing? I have to look up blog posts and videos. I actually found someoneās website that had notes about various features that are better than the docs.
Thereās a delicate balance of signal vs noise.
I used to mock people who make YouTube videos that literally just walk through the documentation. Like bro, get some reading comprehension!
But then when I fumbled with some self hosting tutorials, those YouTube videos were the only thing that made sense, because theyāre explaining why and how.
Sorry yāall.
I worked alongside some technical writers in the early post-y2k years at SCO. This was before they sued IBM for code misuse and died by a million legal and PR cuts, thanks to the āindependent newsā site launched by a ārecent ex-employeeā to reframe things then and rewrite history after.
We had about 15 tech writers in the company, which when I first arrived seemed like a LOT. Iād never met one, and Iād taken a single tech writing course in college as a filler and found it unchallenging work; so I didnāt value them at the time aside from filling a necessary role that your average nerd could surely fill. Then I saw their work; and it was amazing. Itās one of the productās strong points, and 20 years later itās still so head-and-shoulders above the similar offerings by others and since, that itās a joy to read when I come across it.
Quite simply put, technical writers explain something in a logical, sensible way, where jargon doesnāt blind-side the reader and layout and language are consistent and easy. Hell, spelling is correct; which is a big win over 90% of the current stuff. Tech writers are writers as Lance L said, and thus know about adjective order, prepositional placement, the difference between ābackupā and āback upā and all its similar terms; and of course know why e-mail and traffic do not get an S as nouns - ever - even if the popular kids make everyone say it without thinking.
Itās all simple-sounding stuff, and I was fooled into believing it was mundane; but when put together and written with an eye toward a common style it takes a stressful reader looking for a process or a parameter and induces calm for that brief moment required to get into the doc and find the sought-after bit.
Honestly, like the mentors we lost as a working society in the post-y2k bust when the c-suite cleared the ranks of things they didnāt understand, the loss of good technical documentation has a generational effect and will take a massive, sustained effort to reverse.
The worst is when itās buried in Github issues or in a header file with thousands and thousands of lines of code. Yes Iām looking at you DearImGui, your documentation is awful and Iām already being generous.
I just recently started working with ImGui. Rewrite compiled game engines to add support for HDR into games that never supported it? Sure, easy. I can mod most games in an hour if not minutes.
Make the UI respond like any modern flexible-width UI in the past 15 years? Itās still taking me days. All of the ImGui documentation is hidden behind closed GitHub issues. Like, the expected user experience is to bash your head against something for hours, then submit your very specific issue and wait for the author to tell you what to do if youāre lucky, or link to another issue that vaguely resembles your issue.
I know some projects, WhatWG for one, follow the convention of, if something is unclear in the documentation, the issue does not get closed until that documentation gets updated so thereās no longer any ambiguity or lack of clarity.
