How we document where I work

Posted by spin81@reddit | sysadmin | View on Reddit | 79 comments

# Cake recipe Please enjoy this recipe for a delicious cake: the perfect family desert for Christmas. 1. Take a bag or box to put groceries in. 2. Enter, embark or mount the vehicle. 3. Go to the grocery store. 4. Park the vehicle if applicable. Note that it is most efficient to park close to the exit. 5. Leave, disembark or dismount the vehicle. 7. Select the ingredients. 8. Pay for the ingredients (you will need money for this). There may be a self-service checkout. Different modes of payment may be available, including cash, credit card, and contactless payment with your phone. Please find the documentation for each of these elsewhere in Confluence. 9. Place the ingredients in the box or bag you took in step 1. A bagger may be available, if so have the bagger do this for you. 10. Place the box or bag from step 9 in your vehicle. Don't forget the ingredients that are inside the box/bag. 11. Enter, embark or mount the vehicle. 12. Go home. Should you not intend to bake the cake at home, please ask Joe what the appropriate step is here (TODO: document). 13. Leave, disembark or dismount the vehicle. Make sure to take the box or bag from step 10. 14. Enter the dwelling. 15. (Optional) should you wish to defer the baking to a later time, store the ingredients and make sure to store any ingredients that need refrigeration accordingly. **NOTE: an undocumented extra step to retrieve the ingredients is needed if this step is followed!!!!** 16. Bake the cake. 17. Count the number of persons who will be partaking of the cake. 18. Cut the cake in at least as many pieces as you counted in step 17. Detailed documentation is available elsewhere in Confluence, but briefly: it is recommended to cut the pieces so they are not so small as to leave the consumer left with a feeling of unsatisfaction, but not so big as to leave any consumers who like the cake a lot, to eat too much and end up with too big of an after dinner dip. 19. Place the pieces on saucers so that there is a 1:1 saucer to piece correspondence. 20. Place the saucers on the table, one in front of each consumer. To prevent race conditions, imagine a dummy consumer on your own seat, should you intend to consume a piece yourself. 21. Add a utensil such as a small fork by the plate, lest consumers find themselves forced to eat the cake with their hands, which may be unsanitary. 22. Enjoy!

Reply to Post

79 Comments

[-]

YumWoonSen@reddit

At least there's some documentation. I have a teammate that didn't create/share any documentation for over 2 years. And another that has never shared anything in 3 years.

[-]

Hoosier_Farmer_@reddit

Instructions unclear, where are qa validation processes and backout plans? Please resubmit with required director level signoff after infosec review, including these missing details. DR is in scope for this business critical process, so DR Continuity Plan should be attached for the Document Control Repository. Thank you for promptly attending the needful.

[-]

bentbrewer@reddit

Haha. The time is perfect. Chef’s kiss

[-]

Hoosier_Farmer_@reddit

Thanks, don't forget to share positive feedback regarding this interaction with my Supervisory team Colleagues via the 'KuDOS Board' located in the SNOW SteviceNOW 'People Services' (formerly human resources) virtualroom - performance alignments are only a few months away! [Here's a link to the President's last fireside round table describing the exciting career package realignments to be announced Any Day Now™]

[-]

bluescreenfog@reddit

Do we work together??

[-]

Healthy-Poetry6415@reddit

I love you. I hate you also. I will now require therapy for having read these. Its literally the same shit i hear all the time and its so empty and soulless.

[-]

Hoosier_Farmer_@reddit

Wonder sometimes if we secretly work for the same company. It's one that makes 'Path-E-Tech Management' seem wholesome

[-]

Healthy-Poetry6415@reddit

Nah. But when you have these same people that have no ideas and they all just pull the same playbook and then word vomit all over. It starts to feel that way. 1984 was not wrong

[-]

SamTheSammich@reddit

Who hurt you

[-]

Patient-Hyena@reddit

You never worked government IT or a Japanese customer before right?

[-]

straytalk@reddit

🤮

[-]

spin81@reddit (OP)

Thank you for indulging my sarcastic and hopefully funny little rant. For bonus points, imagine that each step has several screenshots. In case I am being unfunny by being unclear: the joke is meant to be that every single little step is present except what you actually want to know, such as which ingredients are needed and the actual recipe. This has been a real source of annoyance for me at work in 2024. Merry Christmas Reddit!

[-]

jaymz668@reddit

just like a youtube video. You need to know a specific piece of info that gets glossed right over

[-]

WWGHIAFTC@reddit

the ones where they obviously run into the exact issue you're having, and the video suddenly just cuts to tj he next step? with no explanation at all how they overcame the issue... screw those guys! 🤣

[-]

redmage753@reddit

I saw this so many times with an atv repair I was following. Drove me fucking nuts.

[-]

WWGHIAFTC@reddit

90% of the time, they replaced a whole component, took it to a shop, or re-assembled it still not working just to finish the video. Pisses me off every time too, lol.

[-]

spin81@reddit (OP)

OMG I felt that. First thirty seconds of hi guys what's good, then one minute of hey you know I've been meaning to make different content for a while, rinse and repeat, all for ten minutes of content with like 3 seconds of relative information of which zero seconds are useful.

[-]

-S3r4ph@reddit

https://youtube.com/shorts/oxJ-trI87U8

[-]

jaymz668@reddit

Changing the headlight on my wife's car, almost every video I saw covered the damn easy side

[-]

Fizpop91@reddit

This is funny I wont lie, but I prefer documentation like this FAR more than documentation that isn’t thorough enough. You cant expect that everyone reading it will have the same level of understanding/experience/etc. I cant frikkin stand documentation that assumes you know a whole lot before starting, what if I don’t? What if I’m a brand new sysadmin/tech/helpdesk/whatever? Help meeee😅

[-]

FoxtrotSierraTango@reddit

Forgive me, but this is one of my biggest per peeves; Yes you should be explicit in your documentation. Simultaneously your hiring manager should be hiring people with a base level of competence for the role they are entering. At a sysadmin level I should be able to say "Connect to the server that threw the alert." I shouldn't have to say "Put your hand on the mouse and slide it across your desk. Note the up/down/left/right movements the mouse makes on your desk correspond to the arrow moving on the screen. Move the arrow to hover over the four squares in the bottom left and then press the left button on the mouse. When the menu comes up use the keyboard to type in 'Remote desktop connection'. Move the arrow to hover over the Remote desktop connection tile that appeared and press the left mouse button. In the window that opens, type in the server name from the alert source field in the ticket into the text field. Move the arrow to hover over the connect button and press the left mouse button." The level of detail should change with the task and audience, but if I have to send someone to a senior center for remedial computer training because they skipped the last 30+ years of home computing, I'm having a conversation with my recruiter and hiring manager.

[-]

redmage753@reddit

You say this, but you leave out the crucial details again, which arent really competence oriented, but knowledge oriented. Connect how? Do you use ssh, or it restricted? Are you using rdp? Is a jump box required due to vlan segmentation? "Just tell by how it's configured." Oh, okay, so for every system I've never accessed, I somehow need to access every switch/router to see what acls, vlans, port sec, etc type configurations are in place (beCaUse the syStEm is tHe doCumEntaTion, hurdurdur) - then review the configured system i don't have access to, to know that it specifically is configured with ssh on a randomly chosen port by the "security through obscurity" guy, meanwhile rdp is setup on other systems, and then this subset specifically requires this jump box, but those ones don't, but they have a different root/admin account than the other standard ones. Oh, and in this environment, you can use your account with escalation, but the other one is root only.¹ And none of *that* is written down. Just a snarky, "connect to the server" line and offhand comments about admin competence. A "connect to the server" level of detail, is unironically a sign of incompetence imo. Not understanding what is important details vs what is fluff. (And not saying this is you, specifically - I'm venting a bit about what I've seen at my workplaces. A connect to the server line is perfectly fine if there is documentation elsewhere saying "windows servers are rdp only on port 3389, Linux systems are ssh on port "2222", except subset b which is on port 22, etc)

[-]

spin81@reddit (OP)

> Simultaneously your hiring manager should be hiring people with a base level of competence for the role they are entering. I would add to this by pointing out that you're saying _competence_ - not _knowledge_, which is a nuance that I feel does a lot of heavy lifting here. A competent sysadmin, if I may oversimplify, knows how to acquire the knowledge to do their job: you can teach knowledge; you can't teach competence. I don't know if it's proper to judge my own competence or lack thereof, but I think I'm reasonably good at rolling with it if I'm asked to administer software/technology I've never seen before - as long as the documentation is decent, of course.

[-]

Fizpop91@reddit

Yup this is completely fair. However not everyone knows all the same things, im a sysadmin with 1 other sysadmin in my team and there have been many times where I knew something she didn’t and vice versa. Also, I LOVE documenting things so I might be biased 😅 but when I document things for my home lab, I have every command that needs to be run, not because I don’t know them, but because its easier to copy paste them most of the time

[-]

tdhuck@reddit

That's the key right there....the person reading it won't be you. If documentation isn't detailed then it is basically worthless. If I'm covering for someone and I've never done their job, I need to be able to follow the documentation and solve the issue. If you say 'web server' and don't list the actual server or IP, that does me no good because there is a good chance there are multiple web servers. Sure you might be able to figure out the one with the issue based on which service is down, but there might be multiple problems or a single problem might be causing multiple web servers to be offline. This is why documentation is hard/never done because nobody takes the time to create good documentation. I'd document all day long and have it be my only job if it paid well. I can't spend the time needed to document if I'm the only one in a 20 person IT department that works on documentation and everyone comes in behind me and uses what I've created and never adds to it. I keep my own documentation and take my own notes for things I've worked on. I've tried sharing it, in the past, but people would never update the document or when it was in a shared location, they would move the document because they thought they had a better place to save it and when I needed to update the document, I had no clue where it was at. This goes back to management because they don't care about documentation until it is too late.

[-]

NoPossibility4178@reddit

You missed the joke but I disagree. I don't wanna tell you how to open a Jira ticket or whatever. Gain basic knowledge on the tools and rely only on KB for knowing what submenus or buttons or 500 character commands need to be executed.

[-]

JustAnotherOpinion21@reddit

Hey fizpop, I think you might have missed the joke. The instructions are clear 'except' for the part that is actually meant to be. Eg there is zero instructions on how to actually bake a cake, despite that being the purpose of the document.

[-]

Fizpop91@reddit

Dammit, you’re right😅 I guess I needed proper documentation on how to read this post. Merry Christmas!

[-]

i_am_fear_itself@reddit

See?! Even thorough documentation doesn't guarantee anything if no one reads it.

[-]

Fizpop91@reddit

Bang on!

[-]

spin81@reddit (OP)

hmb

[-]

MzMag00@reddit

Maybe you need to download coffee.exe and install that first 😆. Merry Christmas!

[-]

Latter-Tune-9111@reddit

the 'bake the cake' steps are defined in the as built document already, why do I need to repeat them in the SOP?

[-]

spin81@reddit (OP)

I feel you, but I would still argue that the opposite helps you more. It's tough not knowing what to Google but once you know, you can keep Googling it over and over again. But if I leave the company you'll never know what kind/flavor of cake I want you to bake unless I document it.

[-]

RaNdomMSPPro@reddit

Triggered. We went down an ITIL rabbit hole in 2006-2007. Hired a former army policy guy (very detailed and good at hounding people to complete their parts on time.) only mark against him was zero it experience. Every procedure was like the recipe, excruciating detail of the inconsequential and then crappy “step 3” stuff because everyone was worn down by the minutiae. More than once I asked him who we were writing this for? Him? Or our it staff who already knew that you needed ingredients before baking a cake. He said you can’t assume people know every step so you have to document. I started prefacing my parts with “procedure assumes reader has x years of experience with the associated technologies.

[-]

redmage753@reddit

As an air force guy who really appreciated how the military ran things, I had the opposite problem. I ask people how do you know what ingredients are needed? Document that. And they go and document "click on the file drop down in the upper left corner." Type instructions, and I'm like, are you fucking with me? Do you not understand what I'm asking? Do you not know? (Spoiler, they don't know how they make decisions). So we end up with someone bringing half the ingredients for chili, and someone else bringing half the ingredients for cake, both get halfway done thinking the other guy is just and idiot, and then both walk away leaving their meals half assembled for someone else to fix later. Close the jira ticket, "completed as far as possible with what I had. Initiate project closeout." Managers high five each other for another job well done. Shit stirs up 3 months later. "Oh. Something must've broke, we will open a new project to fix it." Rinse repeat. Admins go to read their documentation, which says "click on the file button" and not "group a contains x users, group b contains y," etc.

[-]

recursivethought@reddit

that's exactly what i do. i'm not writing a training manual, and I can absolutely assume that you don't assign a baker to fix a car engine.

[-]

dracotrapnet@reddit

I call those "Draw the Owl" instructions. We use Confluence for formal documents and Trello for collecting info on tasks and I usually dump references and a checklist items when I know pre-reqs or steps. Sometimes I add a line "Draw the Owl" when I have no idea and need to sit down and read or find more reference docs, or when docs I found are severely lacking. Sometimes when I'm deep in the weeds on figuring out something I make play by play or as-built docs in Onenote to distill and transfer to Confluence some time. It's just sometimes easier to brain dump into Onenote or trello without futzing with formatting. In Confluence I get the feeling like I have experienced in Word, move one thing everything repaginates and something in the remote distant desert explodes.

[-]

spin81@reddit (OP)

Move a picture in a Word document without every single page exploding challenge: impossible. > I call those "Draw the Owl" instructions. I like that you're doing that as a placeholder. But yes of course that meme came to mind when I was writing the post.

[-]

JohnGillnitz@reddit

Another fun one is referencing another document without providing any clue of where that other document is.

[-]

trail-g62Bim@reddit

Or the other document just repeats things. I was using an app recently that helpfully (or so I thought) had ? next to each setting so you could get a quick explanation. But it was totally unhelpful. It would be something like "Click here to do X." I don't know what X is so I hover and it just says "This where you X. Click here for more info." So I click for more info and the page says "this settings allows you to X." mfer what the hell is X doing??? ALL of the ? were like this. I assume the company had a requirement for this documentation and the guy assigned to it really did not want to have to write anything productive.

[-]

CantankerousBusBoy@reddit

I love the following: 1. All the steps are completely unnecessary except step 16, which has zero information except "just bake it". 2. The annoying strikethroughs. I HATE strikethroughs. Just delete the \*\*\*\* text!!! 3. There is no way the linked documentation exists.

[-]

Letterhead_North@reddit

I got that, and wondered where the comments about the ingredients were. I'd say this shows you were perfectly clear and also funny and, also, hit a nerve with some people. Kudos!

[-]

rschulze@reddit

I really felt this. Once I got instructions to install some new proprietary software and 9/10 pages of the instructions were generic "how to manually install Linux" and the last page was "copy files and database for the software over from some existing installation and delete whatever you don't need" ... this was the first install, we had no existing installation or database. Instructions were obviously written by the software developers who didn't quite think it through.

[-]

Otto-Korrect@reddit

When I was in the fifth grade I had one of the most important lessons of my life that I reflect on constantly at work. Are science teacher asked everybody in the classroom to write down instructions for how to sharpen a pencil. He then followed the instructions step by step from each person. Putting the pencil in the wrong way, turning the crank backwards, pretty much anything that was not specified in the instructions he did wrong. In one instance when somebody had written put the pencil inside the sharpener he removed the sharpener cover broke the pencil in half and stuffed it inside where the sawdust went. I think of this lesson now every time I write any kind of technical documentation or instructions.

[-]

spin81@reddit (OP)

What did you take away from that? I'm asking because I hope for other people's sake it wasn't that you have to specify every little detail...

[-]

AshlarMJ@reddit

Too many details of the wrong thing. Go ahead, try to bake an edible cake with those instructions. There’s no mention of the ingredients!! With any set of instructions, have someone unfamiliar with the process try to follow them. There’s a couple great comments on this already.

[-]

Otto-Korrect@reddit

Not every little detail. More about the importance of not assuming people know things they may not. If this class has been about making the cake, I could see the instructions "put the cake mix in the bowl" resulting in him just putting the unopened box into the mixer bowl. It is too easy to assume that others know what your thought process is and you need to be able to step back and see things as they might.

[-]

spin81@reddit (OP)

That's a good lesson I think. Consider who your audience is when writing something. Easy to get wrong - communicating well is hard.

[-]

TheShirtNinja@reddit

This. When I started my current role and was to begin writing documentation and changes, I was told by one of the other fellows on another team who had way more experience "Write the change instructions in such a way that if an average user was granted the correct access they could complete the change". I've stuck to that since, and while the change managers sometimes get irked because my change documentation can be extensive, I've received nothing but praise from folks who need to perform my changes and have all the steps laid out in such a granular fashion. I typically include: Steps to perform the change, steps to back out the change, steps to validate the change, and depending on what is being changed (like GPOs for example) a document that contains precisely what settings are being changed, why they're being changed, and the scope of those changes. I will never shit on someone for writing detailed changes or documentation, and nobody else should either.

[-]

music2myear@reddit

Instructions unclear: I'm baked, but there's no cake!

[-]

mrcomps@reddit

Just sign up for a free Google account and register as a business. Then you can enter your company name and address. Now you can just Google <company name> and it will come up with the location, hours of operation, website link, and even a map with directions. The best part is that it's all FREE and you don't have to pay some business listing company! You can also register your name and home address as a 'business' so you literally Google yourself and get directions home. It's really handy for when you're hungover or have been up for 20 hours recovering a crashed server, and forget how to get home.

[-]

spin81@reddit (OP)

Let's set up a meeting where we discuss where and how we document how to use Google Maps

[-]

pointlessone@reddit

You can't just have a meeting like that, we need to a fact finding committee first to see if it's worth expending company resources on this meeting.

[-]

fonetik@reddit

If this were real, 100% of the comments would be asking how to make money for #7.

[-]

strangefellowing@reddit

Why is nobody commenting on the real joke: the recipe for the cake was left out.

[-]

SilentosTheSilent@reddit

Error in execution: could not operate vehicle with bag/box in hand. Please advise.

[-]

Gnarlison47@reddit

Man so a coworker is getting close to retirement, I was hired basically to make sure there's coverage when that person departs. Dude literally documented NOTHING his entire career. I am so mad, he hates knowledge sharing too. One of the most insufferably bitter people I've ever had to work with so far and everything somehow relates to politics for him. I honestly wish he'd just pull the band aid off sooner because there isn't anything he does that I wouldn't be able to handle, and I already work in discovery.

[-]

spin81@reddit (OP)

Omg I can only imagine. I have no idea how to deal with this other than make sure there's nothing only he can access. Apart from that I honestly feel just try and get what you can and then be glad to be rid of him when he's gone. At least my coworkers _try_ to document. They just aren't really good at it. They do their best though, bless them. They are sometimes nigh on infuriating but they mean well, I do feel that I have that going for me.

[-]

Gnarlison47@reddit

Dude actually LAUGHED at me with an audience once for typing notes up on something. I called him out on it in front of the same audience and he got quiet for about a month. Something along the lines of "part of the mess of this place is you never documenting anything, and this is what leadership and management expects of us in our jobs."

[-]

omfgbrb@reddit

Step 17 is recursively bemused....

[-]

spin81@reddit (OP)

I'm only just noticing... I was thinking what you meant by it and only now do I see it should be referring to 16. This is partly why I don't like overly detailed documentation. There's too much that can be inaccurate or go out of date.

[-]

klove@reddit

I think you forgot the step to bring the bag inside the store 🤣

[-]

mahsab@reddit

But why is the cake pink? I thought we were making a blue cake?

[-]

8492_berkut@reddit

Requirements were never specified - you get what we think you need. This is my world.

[-]

dbxp@reddit

Don't forget to get sign off from change management before baking the cake, the batter will go off in 3 days but approval will take 1 week

[-]

spin81@reddit (OP)

I am relatively new at my current workplace but have already clocked the change management board as something to avoid at all costs.

[-]

sybrwookie@reddit

You could instead go with the method we use to document:

[-]

Wagnaard@reddit

The cake is a lie.

[-]

rschulze@reddit

Instructions unclear: car ran out of gas and I have 6 yellow sprinkles left over.

[-]

ComeAndGetYourPug@reddit

this is not working *goes on vacation 4 seconds after sending*

[-]

ConstanceJill@reddit

I'm confused. At step 9 it is specifically mentioned that one shall not forget the ingredients that are inside the box/bag, yet at step 12 there is no such mention. Also, would it not be a requirement to know how many persons shall be partaking of the cake (which is only addressed at step 16) before even buying the ingredients, to ensure one has the appropriate amount of said ingredients to make an appropriately sized cake?

[-]

spin81@reddit (OP)

Welcome to my world. I wish I could say I did that on purpose, but although I did notice the belated counting thing, I only saw it after posting.

[-]

dbxp@reddit

I've seen documentation before that would be more like "Count the 10 people in the room and cut the cake into 10 pieces", the fact that the room may not have 10 people in it never occurred to the writer

[-]

sandy_catheter@reddit

I see you've been following me on confluence.

[-]

bryptobrazy@reddit

Love the instructions and then it says please find the documentation for each of these elsewhere in confluence. That really sums it up

[-]

jeffrey_f@reddit

At least you have documentation.

[-]

PsychicRutabaga@reddit

Lol, this is awesome. It looks just like the documentation that accompanies a piece of ~~crap~~software that was handed over to my team to maintain by a third-party subcontractor. Every document accompanying the software has at least 6 pages of high level, generic statements pulled from Wikipedia or somewhere on what this class of software is typically used for in a business setting. But there is nothing substantive about what this software actually does or how to use it. To add to that, the code itself is completely uncommented, uses non-descriptive, generic variable names that give you no idea what they are for, and not a single blank line or bit of whitespace for visual formatting. My holiday pet project during the change freeze is to reverse engineer this mess, strip it back to the studs and refactor to make it maintainable. Appreciate the laugh!

[-]

spin81@reddit (OP)

In a previous job, there was this grizzled grey sysadmin who was the kind of guy who knew everything but also kept things to himself - not out of a sense of self-importance or for job security, but just because that was the kind of guy he was. He wanted to go to the other side of the world (literally) for several months on a long vacation so they said fine but asked him to document everything for when he was gone. He presented this documentation to us and said: "I chose to document the choices I made and the way I configured this, because you can look up everything else for yourself by RTM". I will never forget that, because I found this insightful at the time, but now in my current job I think back to that moment because where I work right now, they - and this is really admirable once you start to notice this, because this takes time and effort - do _the exact opposite of that_. It's kind of mindboggling.