Coworkers writing impossible-to-follow documentation, how to cope?
Posted by Relative_Hippo2549@reddit | sysadmin | View on Reddit | 70 comments
There's a coworker whose docs are so poor, that it makes it impossible to read any text he produces.
A significant part of my job requires that I'd follow his HOWTOs. And they're things you can't just google, they're internal config stuff. Sometimes I offer to make edits and improve their readability (it's on an internal wiki) - but he won't allow such edits, and requested that I'd stop.
We're talking about endlessly-meandering and vague sentences, with little to no paragraphs and punctuation. I'm not sure how much I can post without revealing too much, but here's an anonymized example:
- "Step 12: Active Directory Integration (Internal Domain Only) Please note that these steps apply only to hosts built under the internal.company.com domain. Ensure that DNS for internal.company.com is already configured and that the hostname has been correctly updated in /etc/hosts with the appropriate IP address. Verify that NTP time synchronization is properly set before starting this process. These steps are considered legacy, as opkssh (link to another badly-written HOWTO of his) should now be used for authentication. If you decide to proceed with Active Directory integration, Ensure compliance with all password policy requirements for service assurance. These policies are implemented as part of the OS hardening playbook(Step 3); therefore, the OS hardening steps must not be skipped. Run the following template to deploy the sssd.conf configuration: "name_of_ansible_playbook". Note: make sure you change the "companynameenv" variable to dev/uat/prod in the template extra variables section. Before running this playbook template, please check the login and some_other_login credentials and ensure the password for the user another_login_here is up to date. If the password was last updated more than 30 days ago, it has likely expired. Running the playbook with an expired password will cause it to fail. You can copy the current password from CyberArk.
That's just one paragraph, out of multiple similar documents. I It's not even the worst one, it's just one that has a minimal number of links to other articles/internal hostnames, so it was easier to post.
There is exactly zero quality control over stuff like this. The person who authored this reports to someone who's not technical, has never SSHed into a Linux host here, and has no real way to evaluate this doc - other than, perhaps, for its formatting, grammar and punctuation.
I don't know if this person is a good engineer, perhaps he is, but it's a very, very different skillset to being a good technical writer. I'm not saying I'm the best writer ever, hell - I don't even speak English as a first language myself. But I still do better than this. I think it's not just a language barrier issue in his case, it's just scattered thoughts strung together into sentences.
I'm just ranting I guess. I do get a headache reading this doc. I get the feeling others just improvise and find workarounds to do stuff without following these HOWTOs, which means we have 194,673 different naming conventions, workarounds and duplicate configs.
If any of you is a manager, please reward and promote people who write well. This is the most important thing in your organization sometimes. That's how information is preserved and not kept in silos.
SwedeLostInCanada@reddit
Seems like an excellent use of AI. Parse his docs and have it return proper docs.
Chaise91@reddit
This is the answer. I use AI all the time for simplifying text. I'm dumb so it's a necessity.
HotTakes4HotCakes@reddit
You're making yourself dumber by doing that.
sboyerfour@reddit
You’re going to get left in the dust.
peoplepersonmanguy@reddit
Could even set up an agent, give it examples of good docs, and tell it to turn garbage docs to official docs.
HotTakes4HotCakes@reddit
Why make an agent for that? It's not something you want to do repeatedly.
peoplepersonmanguy@reddit
Because not everyone is amazing like us at documentation, and writing documentation sucks balls.
Relative_Hippo2549@reddit (OP)
ChatGPT is useful for formatting stuff, definitely. I still find myself having to message him and ask, "hey, Brendan, did you mean that I have to skip the first line and install opkssh instead?"
iamscrooge@reddit
Well that’s your answer then - document comms in your tickets and show your manager how much time jobs taking because you’re having to query vague documentation.
Start keeping your own versions of his articles and start sharing them with colleagues.
I’ve had to do this in the past. Long term solution was get promoted into a post where I had clout over the documentation and overhaul the process myself.
DonkeyTron42@reddit
So you want OP to get fired for feeding internal documentation to AI bots? Got it.
delicioustreeblood@reddit
You know you can run sandboxed llms locally right?
SwedeLostInCanada@reddit
jumping to conclusions?
There are plenty of enterprise subscription models. At no point did I say to say to use a public model with internal docs.
Got it?
DonkeyTron42@reddit
Which OP would probably be using if they were available.
purplemonkeymad@reddit
I'm of the opinion that formatting matters. It's one thing to have all the info, but another so it does not take minutes to lookup the information you need.
That paragraph is too big, i just didn't even bother to read it. The "note" should be split out or identified in some way so you know it's not part of the instruction.
It might be verbose, but I'd say "only one step per bullet point." I'd rather 50 steps that are clear than 12 steps that are this mess.
mallet17@reddit
Paste into AI to simplify, and if there's any gaps, ask the coworker.
DonkeyTron42@reddit
The formatting could be improved but the content is reasonable.
ZAlternates@reddit
It really depends.
It sounds like we have “junior” sysadmins trying to follow a senior’s documentation and they can’t. The senior has taken the basics of server building and management for granted. Something like “verify NTP” seems logical to a senior but to a junior, they likely aren’t sure how to even configure NTP, much less verify it is working beyond the clock looks right.
I tell my team to document it as if I have to follow it. I’m a former geek turned manager so I am not stupid of the ways of IT, but also, lots have changed over the years so help me back you up.
Dushenka@reddit
TIL, I'm a senior at 37. Having zero issues understanding OP's paragraph.
Ummgh23@reddit
Google exists
ZAlternates@reddit
A great answer when your boss requires you to document stuff!
Ummgh23@reddit
Documenting is important of course, but certain things should be a given. Document environment-specific things like which NTP Servers are the standard, How timesyncd is configured, etc.
But a Sysadmin should definitely know OR know how to find out how to check it NTP is working correctly on a server..
Just as you shouldn't have to document how to open ADUC or how to log into Entra.
DonkeyTron42@reddit
If the junior doesn’t know how to “verify NTP”, then they need to learn about NTP to be qualified to perform this work. Juniors shouldn’t be running commands they don’t understand.
Kaligraphic@reddit
It would be nice to note whether they're using systemd-timesyncd, chrony, ntpd, or some custom setup. Maybe even the expected time source. (Or if you really want to be convenient, link a standard ansible playbook.)
I've fixed too many randomly configured time sync setups to leave that to chance when there are juniors around.
ZAlternates@reddit
You fail to understand. I suppose I need to make my write up more detailed. My bad. Sometimes it can be hard to write at the level of your reader. ;)
Anthropic_Principles@reddit
Structurally this is poor at best, but the big issue that you've highlighted is the lack of any acknowledgement of the existence and or need for continual improvement.
You've said this is on an internal wiki, but without any acknowledgement that it can and should be improved, it might as well be carved in stone.
Not sure how to fix this without buy in from the top, and it doesn't sound like you will get much support there.
Are there other teams that are collaborating on documentation more effectively that you can highlight as best practice.
Distinct_Lion7157@reddit
Maybe reevaluate your own abilities?
There is nothing wrong with the contents of what they've written. You're lucky you even get ANY documentation. The provided example documentation is not too hard to follow, but if you can't understand it while I (a random person on the internet who has no internal knowledge of your company) can, then you might want to reevaluate your skillset or job.
Distinct_Lion7157@reddit
Maybe reevaluate your own abilities?
There is nothing wrong with the contents of what they've written. You're lucky you even get ANY documentation. The provided example documentation is not too hard to follow, but if you can't understand it while I (a random person on the internet who has no internal knowledge of your company) can, then you might want to reevaluate your skillset or job.
ThePodd222@reddit
Have you spoken to him about this?
Simmery@reddit
I've seen worse.
Relative_Hippo2549@reddit (OP)
Yeah me too tbh. I prefer the guy who writes overly-succinct docs with less info than I need, at least I waste less time trying to make sense of it.
techierealtor@reddit
Another path to look at it is he is being very explicit so you don’t screw something up. It’s a double edged sword. Maybe compromise and ask, can I append a summary version at the bottom that quickly outlines the steps for me next time? Let him have his documentation, supplement it with a concise version and put a disclaimer saying “this is a brief, please consult documentation above for more detailed instructions”
lanekosrm@reddit
They need a copy editor, yeah, but that’s perfectly usable. I’d personally break it out into bullet points, just for readability.
jetlagged-bee@reddit
I agree. I'd break it down into multiple bulletpoints, clearer headings, remove superfluous wording, etc. but it's far from terrible.
AI would be perfect for this.
Oskarikali@reddit
No, this is terrible. Keep in mind it is step 12 of the process and shit is out of logical order. I would be annoyed having to follow 12 or more steps of whatever garbage documentation this is.
Jealentuss@reddit
I was thinking it's a little stream of consciousnessy in the way it's written, as if they write as they are speaking. It's assuming a bit of reader knowledge but I was able to follow along. Agreed with the other posters about breaking it up with bullet points but it is far from bad.
KandevDev@reddit
the way to cope is to write a "translation" doc as you read his. you are going to do the work to figure out what he meant anyway, capture it as a real doc. then when other people complain about the same source material, you have ammunition. eventually management notices that there are two parallel doc systems and forces a cleanup. you cannot fix him directly, you can only create enough evidence that someone above you has to.
RevolutionaryWorry87@reddit
I would use his documentation for first time icdid something then write my own in onenote
ihaxr@reddit
This documentation style reminds me of that TikTok sound...
Master-IT-All@reddit
It really is a wall of text and puts a lot onto the reader to pick up. Does your documentation not have any authorship requirements for formatting? This would be rejected for good reason by my organization's service desk manager.
It really should be something like:
Step 12: Active Directory Integration
Note:
The purpose of this step is to guide the administrator through setup and configuration of Active Directory Domain Services (ADDS) integration for Internal hosts.
Requirements:
DNS must be configured to resolve names in the internal.company.com domain using the specified DNS servers in article: Internal DNS Servers....
Existential_Racoon@reddit
Agreed. Our SPBs and tech notes are writing like your example. Intended result, scope, requirements. These link other docs of needed. Then how to
TheTipsyTurkeys@reddit
Yours writes documentation?
bbqwatermelon@reddit
It always blows my mind what people take for granted. However the question becomes; is terrible documentation worse than no documentation?
thebeardedcats@reddit
Wrong documentation is worse than no documentation. Bad documentation, you reach out, figure out what he problem is, fix the doc, and then you have good documentation.
I wish we had documentation. We can barely get a ticket trail for most of our machines.
Existential_Racoon@reddit
I'm debating bailing on my spit for a better offer, and my notice period (if I do) will be working overtime to shore up documentation.
I hate having bad docs, but i'm OPS so $$ comes first. No matter how much I argue if I get hit by a bus we are absolutely fucked.
probortunity@reddit
Tech writer surfs by
If the company feeds "documentation" into AI, then Yes, terrible is much worse than none.
AI's probabilistic nature exacerbates and spreads the problems of poor doc more easily and quickly with an unjustified tone of confidence.
AvonMustang@reddit
The worst part if you're manually copying the current password from CyberArk when Ansible should be retrieving the secrets at runtime...
Relative_Hippo2549@reddit (OP)
Lots of things here are sadly not very well automated, else we wouldn't need anyone's HOWTOs at all. In my previous workplace, this would have been a 3-clicks thing rather.
UninvestedCuriosity@reddit
There are other central configuration opportunities here as well but you work with what you got or rather meet people where they are at.
It's possible they see their document writing as core part of their reason to exist. The spirit of wiki is continuous improvement. If it's just your own readability and the person has more authority then you, that's about it. You gain nothing trying to solve it for the org except bad feelings from others.
Some corporate wikis have pages that only show to the user that creates them. If changes are easy to track on the central documents, you could spin off your own version that only you can see perhaps and then just keep an eye on updated wiki pages.
Then you could have a little nest egg of documentation that scratches the formatting itch until this person moves on. It's not like notes to yourself is bannable offense.
This isn't a sword worth jumping on op. I find it clear enough to understand but yeah it would make it easier to glance at some bullets and even easier if they would just use some bloody security groups and gpos to set some of these things automatically.
SirLlama123@reddit
this is why i use ai to make my docs. Every time my servers backup and check for diffs it’ll just run through an agent automatically that documents what changed in a change log and updates the documentation
Master-IT-All@reddit
I do this now too for most documentation I want to produce. I'll think up the format and decide how I want it to read and to whom I'm addressing. It can even tell me if I used whom right just now without having to sing Word Crimes by Weird Al.
So the example I posted in reply to the OP, that was my writing because I never intended to write more than 30 seconds worth of my time (I am a fast touch typist for an IT guy). If I need anything longer, I get Copilot to shit out some words for me.
It can be incorrect but at least its easy to read and edit. No wall of texts. Just em-dashes everywhere. (the worst weirdest thing to take from Word)
SirLlama123@reddit
lol i don’t have anyone reading the docs but me hence why i take the lazy route and don’t bother even reading over what the ai makes. I just have a few giant google docs that outline the network and some of the bigger services and a few smaller ones are combined that are more closely knit (kea dhcp, adguard dns, opnsense).
I am only 18 though so i hope my docs come in handy to myself when i try to think why i did smthn
Master-IT-All@reddit
The worst is when you do write documentation for others and they don't even read it and just FAFO through and leave a mess for you to clean up.
"You did what? But I made sure to document how that would be catastrophic..."
So that's why admins at times will get a hold all the keys/cards mentality, a better to do all the work and burn out than try to hand things off and end up doing all the work.
SirLlama123@reddit
all the work + fixing everyone else’s “work”
JeopPrep@reddit
I would be thrilled to get this instead of the non-existent documentation that tends to prevail.
Setup Ollama on a vm and run a local llm. Copy and paste it in and ask it to fix punctuation and turn it into paragraphs. It’ll fix this kind of stuff in seconds.
punkwalrus@reddit
Ugh. I have had developers do this this installation instructions. Many times, this happens:
These clowns never use their own installation instructions, but write something half-assed when they are forced to
RadlEonk@reddit
Maybe I’ve worked in IT too long, but I think it’s actually decent.
Made_UpWords@reddit
Eeehhh, it's not good lol. He's just copy/pasting unrelated shit from technet (wait what's it called now, Microsoft Learn?) lmfao
For 15+ years in this industry writing documentation engenders some kind of high school/college trauma response in me, like I'm doing homework, I'm not good at it. I ask coworkers to do it for me and I take over some of their more "active" responsibilities in exchange. I like to work, I don't like to write. But my personally written documentation is mostly functional, you can get going if I get fired and you have to replace me.
This is pretty bad, I'd just start digging through Intune config profiles or GPOs if I ran into this in a new environment.
Pure_Fox9415@reddit
Yep, it's a shitty doc. Most terrifying thing in it, that it always excessive mentions previous info, give you steps in chaotic order, totally unstructured and overcomplicated. 12 steps? Why it's even a how-to and not a script or playbook?
Relative_Hippo2549@reddit (OP)
There's actually 13 steps, and most of them link to other HOWTOs with even more steps in them 😄
"Why it's even a how-to and not a script or playbook?" -- I'm with you on this. Each step usually involves running some playbook, which quality likely resembles this howto. None of his playbooks just work out-of-the -box, and always require multiple config changes, edits, dependencies and conditions to run. This defeats the purpose of automation IMHO.
My ability to influence things is limited and their team lead is not technical enough to critique any of these processes.
rose_gold_glitter@reddit
You guys have documentation?
KadaverSulmus@reddit
This is easy, make a universal template and announce next meeting that it’s good that everyone writes documentation, but the process needs to be more streamlined so everybody can understand it directly. Propose the template
ProfessionalEven296@reddit
Seen worse… at least there’s something to start with. Leave his documentation alone, and start your own in a different system. Have links back to his just in case he’s hidden a nugget of knowledge in there.
His version would not fly in our system; we’d rewrite it in English.
Relative_Hippo2549@reddit (OP)
That's what I often do. And I add screenshots with relevant bits circled in red. Anything I can to reduce ambiguity.
sryan2k1@reddit
That example seems perfectly fine.
Master-IT-All@reddit
No, it's hot garbage. I didn't even read it for technical, it's a wall of text.
Relative_Hippo2549@reddit (OP)
I see it as a lot of "what not to do" sort of advice, more than what to do.
Another issue I have is that there's a list of steps early on, and then at the end of the sentence - it tells you to not actually do them, because opkssh replaces them and they're actually legacy (and that's after spending some time on those!). But it doesn't tell you if this opkssh software needs installing instead. There's a link to another doc, which doesn't really answer that question either.
My one achievement is getting him to add that final "You can copy the current password from CyberArk" line. I tried multiple other commonly-used credential sources here before I found the answer to that question. Every time there's uncertainty in the text, I end up spending a bit of time
GX_EN@reddit
Who do you work with? This is unbelievably bad.
stebswahili@reddit
Others already said it, but seriously. AI. This is what basic LLMs do best. If you’re an M365 shop Copilot offers the path of least resistance and security.
Danowolf@reddit
Make him run it through Claude and have Claude create the document.
SilentBuilding3915@reddit
That looks like he's either copied the Microsoft knowledge base article or Microsoft design considerations documentation verbatim & passed it off as documentation.