What makes documentation "good" in your eyes?
Posted by Dense-Land-5927@reddit | sysadmin | View on Reddit | 117 comments
Hey everyone, I am currently a Jr. Sys Admin in internal IT. At the moment, I'm going through some of the processes my supervisor wants me to learn (specifically with Linux since we use it a good bit). Essentially, he's given me some basic task in Linux so I can get the hang of the command line.
I am also wanting to document the steps involved in installing things like MySQL, Apache, etc. In your opinion, what makes documentation "good" documentation? I am wanting to work on that skill as well because I've never really had to do it before, and I figured that it would be something useful to learn for the future. Thanks everyone.
LincolnhamLincoln@reddit
Don’t make assumptions about what the reader knows. Explain it so someone with no knowledge of the subject could follow it. Examples of the commands to run. This kind of goes with the first one, avoid acronyms. Especially ones specific to your industry/company.
Ban-evasion4@reddit
Or, put the assumptions in the reader should be aware of.
That's how our documentation template works, one of the first sections is -
Assumptions for the reader, knowledge, permissions etc
LincolnhamLincoln@reddit
I’m not trying to convince you to change how you do your documentation. OP asked I responded.
Ban-evasion4@reddit
I didn't think you were I was just carrying on the discussion :)
lifesoxks@reddit
I'm not sure i 100% agree on this. A system aimed at specific people should take into account the skillset of said people.
If I'm documenting a system that is to be used by IT I doubt I would explain the syntax needed to ssh into a host because I can safely assume IT should have basic knowledge about connecting into a remote cli, and I just might document something to the extent of "ssh into x.x.x.x using your admin credentials", but explaining the same to someone from accounting would go something like "open putty and in the box labeled host name enter yourusername@x.x.x.x [insert screenshot] Click connect aprove by pressing the accept button [insert screenshot with arrows pointed at the button]
Enter yous password, it will not show you entered any characters"
Information that might be needed for some people might become tiresome to others, thus understanding the ability and knowledge of the expected users might make documentation vastly different
Raskuja46@reddit
This headspace is how we end up with documentation that makes me want to hogtie people over a firepit. What's obvious and assumed knowledge for you is not going to be the case for whoever ends up having to read your documentation. You put in enough years in this field you eventually learn to stop assuming there will be a baseline level of knowledge beyond the most junior of neophytes.
TheCollective01@reddit
Couldn't agree more. I'd rather have information I already know that I can easily skip over, than not have information I need because a lazy asshat brought some real "Step 1: draw a circle, Step 2: draw the rest of the owl" energy to their documentation 😡🤬
rosseloh@reddit
I understand "how to ssh into x.x.x.x" but in my case can think of a few other things: for example, how 3/4 of the stuff I manage at my current place, I had to figure out how to manage with google-fu and prayers that the creds were stored in previous IT's password manager (or were the same as something that was stored there).
I know how to do a lot of that now, but for me, documentation is 90% about the "hit by a bus" scenario where someone is taking over from me with zero industry specific training, and 10% process documentation for current folks (that can also cover that new person if necessary.
LincolnhamLincoln@reddit
You would think you should just be able to say “ssh to server x”. But almost 30 years in IT has taught me that someone is going to ask, “How do I ssh?” Also not everyone in IT is technical. Our analysts are in IT and they would need clear instructions and I don’t want to write different versions for different audiences. I’d rather the documentation be thorough and tiresome for some than not thorough enough.
webguynd@reddit
IMO, I prefer these "docs" to be code. Things like this, in my land, should be getting taken care of by Ansible or some other automation/configuration management. It's all in a git repo, and the readme describes the roles & playbooks.
If docs are in the form of manual step-by-steps w/ screenshots, etc. then to me that's a process failure - very rarely should something have to be done that way - it does happen, for sure, but shouldn't be the norm. Even on Windows nowadays, almost everything can scripted with PowerShell.
So, my teams docs are basically git repos, some readmes, and network/architecture diagrams (these are important also, as long as they stay up to date). Changes are done via pull request.
End-user facing docs on the other hand are a different story. For us, we have a space on confluence for those and takes the form of more traditional documentation - screen recordings, screenshots, etc.
boomertsfx@reddit
Amen! All this old school manual documentation is bush league IMHO
knightofargh@reddit
Complete, current and versioned. A change log is a nice to have.
knemanja@reddit
Does anyone have an example of such documentation?
GullibleDetective@reddit
With a date stamp, table of contents, references or important links
TipIll3652@reddit
And structured. I can't stand rummaging through docs that are all over the place.
knightofargh@reddit
I see you too work with people who think Confluence is a good document system.
dak_gg@reddit
wait, what's wrong with confluence? (genuinely asking)
420GB@reddit
The most egregious problem is the search functionality. It sucks.
knightofargh@reddit
Non-technical people who don’t understand markdown and its versioning leaves a lot to be desired. Internal search in my experience is pretty dire. This could all be that the ops guys who document in it are bad at their jobs, but in my experience it looks shoddy and does not do its job well. I just opened our internal one and saw four different formats on just the left heading bar. I clicked into a couple documents and they all looked like a toddler laid them out. I don’t see style enforcement and this company is ridiculous about everything matching their branding usually.
As someone else said, use git since it’s cheaper and actually keeps versions. Or SharePoint. At least SharePoint can kind of enforce style, still not great at versioning.
TipIll3652@reddit
Shoot, the people I work with write documentation like it's their version of a "Choose your own adventure" book. Except they forget to tell you to flip to page 30 if you decide to fight the skeleton army or page 46 to rescue the princess.
jdsmith575@reddit
And easy to search for. Include the terms a reasonable person would use when searching for this info.
1337Chef@reddit
Yes, but not too much. The documentation must assume that you understand your job. Easy, step by step
knightofargh@reddit
Depends. If I’m L4 engineering making docs for L1 offshored Helpdesk you better believe it’s step by step and has pictures with boxes and arrows. Idiot proof your L1/L2 docs and update them when they build a better idiot.
the_federation@reddit
Adding onto this, sometimes it's not even L1/L2 teammates reading the docs. There's a senior admin on my team who can run circles around me in technical skills, but I have more experience in one platform we use since I'm the primary admin for it. He had no experience in it, so when I had to walk him through doing something in it, I had to explain it in detailed L1 terms.
1337Chef@reddit
Well, thats true. I was thinking of docs for your colleagues doing the same work or the next guy taking your job
Alapaloza@reddit
Aka markdown with git in a repo. Then you have all you need
knightofargh@reddit
I mean… you have git. I’m not sure I’d let end users loose in a repo trying to find documentation but for code and declarative IaC it’s certainly the most standard tool.
matt95110@reddit
So when I told my colleague that his documentation that consisted of 3 out of date Excel spreadsheets and a Visio diagram dated in 2016 was no good, I was sort of right lol.
general-noob@reddit
It exists and updated
whirl_and_twist@reddit
hahahahah you nailed it. good private docs are the exception in most cases, we have all dealt with a clusterfuck of code that only one guy knows how it works, and "its all in his head", as if this guy was beethoven. please, tell me more about how you have no life and love to be awakened in the middle of the night or bothered on a sunday cause only you have access to the thing.
Swordbreaker86@reddit
Write down literally every step you take for the process. Include screenshots. Make it foolproof. Preferably, do all of this while walking through the task.
Assume you die tomorrow, or your brain is wiped and you forget every single step. You should be able to walk through the documentation still.
serverhorror@reddit
I hate Screenshots in documentation.
It's the worst method to document anything.
Just a bullet point or numbered list. Please do not add screen shots.
krazykitties@reddit
Only screenshots is bad, but no screenshots is needlessly restrictive. You can communicate a lot of information in a screenshot that is difficult over text. For the first time doing things, it sure helps most people to have some visual representation of what they are doing.
serverhorror@reddit
Like what?
How to exit vim?
Zenkin@reddit
I hate video much more than screenshots. Especially when it's a 20 minute video and you're only looking for a fifteen second section for the step that you're missing.
No_Investigator3369@reddit
What if it has the breaks and hyperlinks to the different subject matter?
Zenkin@reddit
Still no. I just want instructions which are written down. I can accept pictures and videos which are supplemental, but I want the core documentation to be printed words.
malikto44@reddit
I'll take screenshots, but just trim it, if it is relevant. I have found that without them, a lot of people get lost.
plumbumplumbumbum@reddit
I find that overly trimmed screenshots can be counterproductive. Often, they isolate only the error message or a single window, omitting valuable context. In documentation, this frequently results in screenshots that show just a popup or dialog box, without surrounding UI elements like menu paths or navigation breadcrumbs. When the interface changes, these missing elements can make it difficult to locate the relevant feature.
One recurring issue I’ve encountered involves a particular service desk team member who consistently escalates tickets with screenshots that only capture the error text—no surrounding application window or context. This makes it challenging to identify which application generated the error. Additionally, since the text is embedded in the image, it can’t be copied for further research or troubleshooting.
No_Investigator3369@reddit
This is because they are grasping at straws, they know if they include the whole thing you'll just kick it back and say "that says SQL error up above this is not a bgp ASN issue" in my experience. And then you ask them for system logs on their side and you would think you asked them for a 25g bar of gold.
PitcherOTerrigen@reddit
Worst sysadmin I ever met didn't believe that you should write documentation. He believed it enabled out of scope technicians to do.... Something never really made that part clear.
Frankly I think he was just gaming job security. I bet the current company he works for is a mess.
come_ere_duck@reddit
This. Some steps may seem like "well no shit" but some people really need that level of clarity. It also helps for when UI gets updated and certain labels have been changed.
andpassword@reddit
This is essential, but not complete. To be truly "good" to me documentation should also have a single-page summary explaining what the business need / relationship is for the process being documented.
e.g. "This document describes the installation and setup process for SFTP server on the endpoint sftp.company.com. This service is relied on by Finance/Accounting, Data Ops, and the ERP team. To execute this document you will need the following things set up (list).
After setup is complete you will want to refer to document #X123 for managing identity/authorization on the completed system."
This allows someone to instantly see if they are in position to use the document you've created, or if they need to set up something else first, or etc.
This can also be done with a proper wiki / linked document setup. But the upshot is this: the relationship between all documents is a vital part of "Documentation" and is what sets apart 'good' documentation.
lordjedi@reddit
This is good! Going to start adopting this!
corruptboomerang@reddit
I personally, love WHY everything is done somewhere in the documentation too. Like okay great I've got all my settings the same as yours, but it's still crashing -- because in the documentation it's set to '1920*1080', and I'm now running a 4k screen... You tell me that 1920*1080 is the resolution and this may need to be adjusted if the resolution changes... then I don't have to go on a journey of discovery.
jamesaepp@reddit
At the very least I'll play devil's advocate here. If you want to write down every single step, what's the point of a document? Just open OBS and hit record, and talk through what you're doing.
To be honest - that's what I do a lot of the time.
A key part of documentation is also that it should be easy to update, and that means you need a little bit of wiggle room as to how detailed you're going to be. Some items in documentation/steps need to be left up to the competency and discretion of the administrator or moment.
ThemB0ners@reddit
Videos are easy for making documentation, but awful for reading it back. It's so much quicker and easier to find the part you need in a static document/images.
jamesaepp@reddit
I agree, but then the input effort to create the documentation skyrockets.
Fast. Good. Cheap. Pick two at maximum.
hawk7198@reddit
Because sometimes when going through documentation I'm just looking for that one specific part of that one specific task and I'd rather scroll to page 6 (or ctrl + f) then try and skip through a video to find exactly where it is. Also the ability to copy + paste from written documentation.
Swordbreaker86@reddit
Video is acceptable documentation.
I would agree you SHOULD be able to assume a level of technical ability, but I have had to add very basic Help Desk level instruction in my documentation for some team members who are stronger at other tasks.
And to be honest, I document for myself for those times when I have too many tasks and I cannot remember how I rolled out software from 4 months ago because it's a once in a year install or something.
cjbarone@reddit
When our org moved to a new server setup, that's what we did for testing our documentation. As all our sites were siloed from each other, each tech would be setting up new AD-based Samba sites at each physical site. We had just hired someone a few months earlier, so we had them setup their site following our written documentation, and to mark where things did not go according to plan.
We looked at the process, figured out the issue, then updated the docs. We burned down his server and had him redo it with our updated instructions. It got him used to our setup process (bonus), and we got the newest person comfortable with some of our most prized systems (bonus)!
With it being Linux, we didn't use any screenshots, just text.
KN4SKY@reddit
I passed the OSCP last year. You have to write a pentest report to pass. The exam overview stressed that it should be reproducible. The graders presumably don't care that much about spelling or grammar as long as someone can look at the report and reproduce the steps in it to get the same results.
At my current job, my internal wiki articles include lots of screenshots and command snippets for exactly this reason.
jdsmith575@reddit
And take your time with the screenshots and use a good editing tool. The full screenshot of your 4k monitor that includes multiple windows isn’t helping anyone. (Unless you need multiple windows to present the info.)
Mandelvolt@reddit
I always like to have a little drag and drop clock app that I can drag to the corner of my screen shot, helps with compliance audits and knowing if the screen shot is still relevant. Screenshots are under appreciated in technical documentation.
whirl_and_twist@reddit
plenty of good comments here but if you can include logs that is extremely helpful as well. even a wireshark data dump of a couple minutes worth of data sharing, or a huge java log file can be very useful for someone who knows the place
GullibleDetective@reddit
Explain the why the setting was chosen over others
Screenshot with arrows or boxes and ordered numbers
Ordered steps and sections for alternative options, like setting up new ssl VPN (habe a section for ldap AND local logins if you configure it that way).
Completeness
Common issues and fixes
kyloth89@reddit
Ever watch the dad who asked his kids to write the steps to make a peanut butter jelly sandwich? He is the reason my documentation has steps, pictures, notes, supporting urls, table of contents and constantly being reviewed!
billsand2022@reddit
A walkthrough with screenshots that is peer reviewed is what I do. If someone else hasn't replicated my work from my walkthrough, I'm not done.
chaoslord@reddit
Documentation needs to ensure someone can re-do the work you did. Complete steps are critical.
SayNoToStim@reddit
at 3 AM with a hangover.
Because sometimes, you are at guy at 3AM with a hangover.
chaoslord@reddit
Hahahaha so true
HylianSystems@reddit
This is one of the reasons a lot of MS documentation sucks. It sure tells you a lot ABOUT the feature/function/process, but how to actual DO what you need to do is missing.
TheCollective01@reddit
Yep, there's real "Step 1: draw a circle, Step 2: draw the rest of the owl" energy in lots of help documentation for these giant services, not just Microsoft but Cisco too among many others..
vi-shift-zz@reddit
I write documentation assuming the person reading it has no background in the environment or technical knowledge.
Include tickets, explain how this ticket relates to what systems. Background and context as I discover them. Often I'm the first person translating decades of knowledge passed down worker to worker.
Documenting forgotten workflows, programs written by programmers gone for 7+ years still in production.
I'm always thinking of the next person, create what you would like to have coming into an unknown environment.
Sasataf12@reddit
If it's useful.
That's it.
rs232killer@reddit
Tell them what it's for
Tell them how to use it
Tell them how it's configured and why
Tell them how to support it
Tell them references and additional help.
Have someone test it.
Break out snippets
Include appropriate diagrams, ports, unique config details, ips or addresses. Any relevant or necessary logical, physical or power diagrams
come_ere_duck@reddit
The why is so important. The amount of people who break shit because they think they can "improve" something without knowing exactly why it's configured the way it is.
4thehalibit@reddit
When I let you read it you should have no questions
lordjedi@reddit
Can someone else pick it up and run with it?
Will that person be a Linux admin or a Windows one?
I'm in an org where most of our admins are Windows guys, so any time I write Linux docs, I write it like they have no clue what to do.
the_federation@reddit
Unfortunately, I find that this is something I actually need to say: don't just copy pasta from an LLM. Multiple times this past month, I asked people in my dept for info and when I asked them to clarify something they responded something along the lines of "Idk, that's what Copilot said."
Be detailed in the steps. Don't just write "Click the button", write which button needs to be clicked (and yes, that's something I saw in documentation).
If you're writing something for users, make sure it's actually readable by the average person. Don't assume that users know anything about technology. Whatever minimum level of competency you think users have, lower it because a lot of them don't even have that and will have no idea what a "browser" is. If you can have a user look it over, that's even better. I have my wife look over emails I send because otherwise people don't understand them.
assassinboy4@reddit
there is documentation and I can access it
Overdraft4706@reddit
That anyone can pick it up and follow it. I do my documentation very detailed with lots of screenshots, lost of explanation's as well. Also i put at the top, what you are going to need and where to get it.
Beginning-Still-9855@reddit
To me, it's good if you could follow it on your first day in the job and do it right.
ObiLAN-@reddit
One piece of advise I'd give that doesn't seem to be mentioned is:
Test run the documentation after it's created to make sure it works. Then if possible have someone else do a test run.
Helps point out those things that are obvious to you, but may not be to others.
Flaky-Gear-1370@reddit
Documentation that is to the point and has the details relevant to your specific solution
I don’t need you to badly cut and paste screenshots that will be out of date in three months
higherbrow@reddit
Perfect documentation is structured, searchable, and has keywords to help find information. It's complete, contains every step of the procedure. The basic procedures should be executable by a non-technical employee that was granted admin rights with how clear, simple, and complete the instructions are (though trouble-shooting, of course, would likely be beyond them, should something go wrong).
The more complete the documentation, the more important the searchability is. Just "sorting" it isn't enough.
neckbeard404@reddit
This is what you need to know cheat .
net1994@reddit
No follow-up questions and plenty of screenshots.
raxxius@reddit
I has change logs. It better be idiot proof. Screenshots + videos + numbered steps.
myutnybrtve@reddit
When the multiple people using it ate all on yhe same page as to how its being used and what its being used for. Im sick to death of every employee coming up with their own way of making a note of aomwthing in a shared aystem. What is the point of a shared system if you refuse to search for the object / file that already exists that serves the same purpose as the one you are creating. Just fucking no. Maybe if anyone searched searched "nameof the fucking server" and note there dated xhange yhere then we wouldnt have 20 different entries for the same goddamned thing and wonder which is relvant to what im doing. And thats even within the same documentation system. Everyones off doing their own things with text files and word files and spreadaheets. You think you are teyingto keep your atuff straight? Maybe you are, but its just for you and its selfish. And it hurts everyone when you get hit by a buss or are sick or whatever. Cant we just talk about it? Cant we just do what we say when we say we are going ro stickto the one system and use it as intended? Cant you ask if you cant find what you need before duplicating ad nuseum. Arrrggfh!
Dense-Land-5927@reddit (OP)
I appreciate all of the comments. Lots of things to take into consideration! Can't answer to all 72 responses but I do appreciate all of the feedback!
Heuchera10051@reddit
Start at the beginning. No, not that beginning, the actual one.
I've seen documentation that starts with a specific app, on a specific machine, already running and open. That might work if it's a part of a larger set of documents, but this wasn't the case at the time.
Tell me what machine I need to log into, if there is a specific user account that needs to run the service, what the IP address or URL is needed to get to the web interface....
You may even need to mention where the machine is, especially for network gear.
I always write assuming that my documentation was just handed to a temp with no knowledge of the environment. I will mention specific log in names if they're relevant to the process being described, but NEVER include passwords.
svarogteuse@reddit
Its has the information needed in a quick manner. I dont need a comprehensive description of every button and menu option I need to know how to do X task.
Kitchen_Image_1031@reddit
Depends on the timespan… it cannot be 100% verification for everything.
Ie- We have certs due after a 10y expiration.
The good and the bad. Good- Spending just enough time to keep up with it is crucial.
Bad- Only pointing to growth needs based off of old documentation is not a wise idea. If someone were to rebuild all our servers with dated cert practices and our endpoints went offline in dev/QA, and prod never sees the cert, but the cert is due, then it’s a disaster either way. Mostly because now we are out of time, and none of the old documentation worked correctly with the new systems.
So I believe in directional integration of future systems where an org must have someone that is always researching new technologies and cutting edge focus to prep teams on legacy projects and new projects. That can be a very difficult task for many who specialize in one area while trying to keep up with figure upgrades, but missing the macro picture of an org’s figure capabilities in terms of macro performance.
Ie- Proprietary servers that cannot be mixed with untested robotics assembly lines. Some clients that work multiple areas of integration, I see those techs and admins go crazy when they’re told they have a new client that needs QA at a new site they’ve never seen or handle mainframes for.
Coffee cups ready for long nights and lots of meetings. The documentation required for these overhauls is beyond my imagination, and many of them are written horribly between Asia Pacific teams and Americans.
2Tech2Tech@reddit
when you write it so anyone can read and understand it, not just personal notes for your own self
sunnyswtr@reddit
Imagine its 2am and you need to get from start to end of a task using your documentation - it cant be complex because its 2am and youre half awake but efficient and detailed enough to get you though because there is NO ONE else around to clarify. When youre done attach a version number, add a changelog and byline.
Valdaraak@reddit
Can I hand it to someone fresh out of college (or even not in IT) and they be able to perform the task? If yes, the documentation is good. If not, the documentation needs work.
A_Very_Shouty_Man@reddit
After a long time defining standards for things including documentation, here are my 3 key takeaways based on the approach "Imagine all of IT got sick tomorrow and your company needed to bring in contractors. What is the minimum level of documentation necessary to enable them in relatively short order to get a decent understanding of how the service works?":
Guide: As many others have said, there is the "dummy's guide" method, with screenshots, and big red arrows "Click here", then "Click here". This could be the Admin Guide, User Guide, or both, as needed
Technical config: The LLD, design doc, "As built" doc, DAR (Design Alignment Report) needs to give details of every aspect of the service and how it's configured - network, database, app, etc, as well as any API or inter-connectivity information, licensing, all that reference type stuff
Create templates for the 2 above items that hold all the necessary sections. Use them every single time. IT people will get used to the layout and structure, and quickly be able to go to the relevant section
mariachiodin@reddit
I like my documentation to be as minimalistic as possible, and some visio of network topology
chefnee@reddit
Red arrows. It denotes something important.
PhillyGuitar_Dude@reddit
If it hasn’t been said, I would add clear structure and formatting and don’t rely entirely on screenshots. Assume that your documentation will be indexed by some type of internal “AI search” feature.
Raskuja46@reddit
It helps me solve whatever problem I'm running into without having to intuit too much of the connective tissue of whatever problem I'm wrestling with. I don't think that's the answer you're looking for though.
If you're documenting a procedure, my recommendation is screenshots with bit color coded circles and arrows showing each step visually so that the person making use of it can just following along on auto-pilot but can still drill down on the details by reading the more thorough written description.
latechtech@reddit
If you use documentation from a URL put the URL in the header somewhere in case you have to do it again. For instance, Carl Stalhood does an excellent job of documenting all sort of things and usually has the latest up to date version when a new version comes out. He also has comments open on it so if you run into a particular issue and he has time to respond he will. If you are there long enough you will be doing something again and again.
Carl Stalhood – Filling gaps in EUC vendor documentation
Flashy-Dragonfly6785@reddit
this is a great question. I think one of the reasons why it gets so difficult is because they are actually many different types of documentation for many different purposes.
One way to look at it is like this: https://docs.divio.com/documentation-system/ - personally I found it really helpful to try to figure out what type of documentation is required for a specific thing rather than just worrying about producing "something" which may or may not actually be useful.
elliottmarter@reddit
I write two types of guides.
The first type is some sort of basic process which I would expect a new hire to be able to complete, this is written in such a way that they can follow it, it's not verbose, but every step is there and there are screenshots to indicate the correct way to do something a bit complicated.
The second type is for a senior engineer, they know what they are trying to do but aren't sure of the process. This will contain code examples but it won't say you need to connect-exchangeonline first (for example).
Personally the guide needs to be easy to read, not a wall of text.
Break it up with panels and examples and screenshots.
Squossifrage@reddit
Inclusion of the date the documentation was last updated, by whom it was updated, and information about the environment such as versions of everything.
Squossifrage@reddit
Searchable keywords.
LOTS of searchable keywords.
serverhorror@reddit
Leave out the "big words". Just tell people facts.
Provide a separate section that gives examples.
Provide a third section that has examples and explanation of why settings work the way they do.
If you talk about inventory style docs:
Forget long form text, just give me a table with all the facts (as in observations, properties) and give me a system that I can use to query in a script and then apply things to the resulting set.
unccvince@reddit
I hope you will not be using screenshots for documenting Linux steps as many suggest, use markdown or rst, and never use a word processing program, it will change important information into unwanted emoji.
beermayne@reddit
readability, formatting, aesthetics, grammar, understandability
ApricotPenguin@reddit
The wide array of answers you're getting here shows how widely people interpret what is "good".
One thing to be cognizant of is your target audience - after all, you don't want to describe the "obvious" things to know, such as how to launch an application from the start menu, or where the Program Files folder is located, to a technical audience.
But even then there will be varying understanding. For example, not everyone has a basic understanding of what DNS is.
For me, I consider documentation to be good enough if someone is able to reproduce the end result, but starting from an approximate equal initial state as me, and following the steps as described.
Xibby@reddit
Depends on the target audience.
Lots of my documentation targets someone with similar knowledge, experience, and wisdom should be able to follow it.
Or if it’s a task being handed off documentation will be written to that level.
Keto_is_my_jam@reddit
Good documentation is that which is pitched at your level of knowledge and leads on from there, matching your growth and understanding. It explains terms you may not know. It's so hard to find!
entirestickofbutter@reddit
if its funny
AdUnlikely7230@reddit
who, what, when, why and where is a good start. I've seen plenty of documentation over there years missing this info.
223454@reddit
First, decide who the audience is. End users? Interns? Techs? Yourself? People at your level? More senior people? A senior person may just need a rough guide with notes, but an end user may need complete step by step instructions with pictures. Regardless, make it clear, accurate, as detailed as needed, organized, structured, versioned, etc. When you're all done, have someone else follow it to verify. Then keep it updated.
OkIndependent1667@reddit
Its written in a way that if i’ve never even seen the product its for before i can get the desired results
Sensitive_Scar_1800@reddit
Document, standardize, automate. IT organizations who practice these steps are light years ahead of those that do mot
Spare_Pin305@reddit
Documentation that is written for a person who isn’t an engineer, and explains why we make the setting or why the button exists.
424f42_424f42@reddit
Depends on exactly what. But for some stuff I also think of it as, could my mom follow this with minimal prep. That's not 100% foolproof level, but close enough (fool proof takes a lot more time to document)
My mom is not a technical person in her 70s, but she can do what she needs, is an ok user, and can do some basic trail and error troubleshooting on her own when stuff doesn't work. I have some complex changes that I feel I could give her about a 15 minute lesson on basics (stuff I'd expect a week old worker to know) and she could follow the change plan.
RhapsodyCaprice@reddit
A lot of good comments here. I'd also add peer review. Get your SOP to where you think it's 100% bullet proof and then have someone else try everything in it. That will tell you if you're actually doing a thorough job or not.
ACL_km@reddit
TheKingofTerrorZ@reddit
If I open it in 5 years I wanna understand what I need to do. I’m talking step by step explanations, screenshots with big red arrows or circles, maybe numbers to indicate what order it needs to be done in
rybl@reddit
Step by step process documentation is good and really important for many processes. However, the documentation that I find most valuable is the documentation that provides context. Information about why something is configured the way it is is invaluable when returning to something you haven't touched in a while or that another person or team set up.
Cookie_Eater108@reddit
My opinion, not a scientific one at all and im sure you could find better answers:
Good Documentation has:
- A clear documented reason for why we want to do this, stating the intention of what the documentation is for. Apache HTTPD is a daemon for delivering websites- it allows websites to be hosted on a server.
- a clear breakdown of the requirements needed to get started, or foundational knowledge that you need before entering. Before installing Mysql you should have a server with a minimum of X GB free disk space- Y processor, Z RAM and you should be comfortable with the Linux UI, CLI and Yum/Apt-get
- be written for the correct audience. If you're writing this for a senior technician then you can make things more concise, for example 10.10.10.10:443 instead of Be sure to connect to the instance you created in step 3 and ensure that port 443 (HTTPS- the secure website port) is open, you can use to check if the port is open. A junior audience might require a bit more explaining- if you're writing for a non technical audience then this is even more important- especially something that will be pulled in a business continuity/disaster recovery time.
- A basic revision history. It should be clear that this is troubleshooting a particular version, in a particular year. Apt-get update might be deprecated by the time 2040 rolls around.
- A table of contents. Sometimes you find a document that looks like what you want but isnt what you want- skimming a table of contents lets you figure that out quickly. Document Title: Resolving Windows Update patches breaking production. Chapter heading: How to download linux.
Bad documentation has:
- Barrages of acronyms or shortforms, especially when the document is used in Disasters/business continuity or is meant for a junior audience. The CXE needs to be post-oped to MMV via SCMP. Always APT to avoid a CVE creating an ISIR.
-Flows in a non-linear or non chronological format. See Section 3 for more details. Section 3 redirects elsewhere.
- For non BCP/DRP documents, absolute addresses or names that are referenced. If in doubt, contact John Smith @ ext. 50 or pager number 555-555-5555
Inevitable_Score1164@reddit
Assume that someone who has zero knowledge of the tools or the process has to complete the task. Will they be able to do that from your documentation?
GrayRoberts@reddit
It is easily ingested and indexed by an LLM.