Selfhosted

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.

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.

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)

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.

Yes @Voroxpete@sh.itjust.works, please do share recommendations

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.

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.