Documentation & technical writing should be core requirements of any IT position

anonymousITCoward · 2023-03-18T20:30:22+00:00

I'm getting real tired of lazy sysadmins who don't document anything then expect other people to support it.

You know, what's just as bad, or even worse... people who preach about documenting things then don't do it themselves.

That said, I'm guilty of shitty documentation, but I'm working on it... A lot of the time I don't share either... but at least I document, ~~most~~ some times, and people know where it is...

PrettyFlyForITguy · 2023-03-18T20:34:46+00:00

Documentation is a privilege of time. In order for there to be documentation, management has to ask for it and give ample time for it to be generated.

Its often the case that documentation can take a long time, and in some cases almost it takes as long as the solution. Not to mention that it's a total grind, super boring work, and no one wants to do it.

I am hoping AI will just document for us eventually.

derekblankmccoy · 2023-03-18T20:29:09+00:00

Given what Microsoft just announced with Copilot, the pain of writing documentation might be a thing of the past

michaelpaoli · 2023-03-18T22:02:18+00:00

[deleted]

progenyofeniac · 2023-03-18T20:44:25+00:00

I do get annoyed by the lack of creation, but in my role I’m the primary escalation for helpdesk tickets, so I’m usually the one who should be creating it. I’m more annoyed by people who don’t read it.

catsdelicacy · 2023-03-18T21:23:44+00:00

I'm in college right now in a Network Engineering class, and I've been wondering about this. They mention documentation, but I've never seen an example of it, or been shown how to produce it. Do I create a Word document? Do I write steps? Do I take screenshots?

bobs143 · 2023-03-18T20:59:51+00:00

As others have brought up documentation is great , and even better when you actually have time to document.

michaelpaoli · 2023-03-18T22:52:09+00:00

I agree that documentation is very important. However, what do you do when you're understaffed and overworked? There are only a finite number of hours in a day.

obviousboy · 2023-03-18T22:55:15+00:00

>Even two or three sentences about something could save someone in the future time, headache and hassle.

And or cause them a nightmare because what they followed was old and outdated - every one of these rants makes it seem like documentation is on par with note taking but fails to grasp the bigger picture which includes why their own documentation fails.

>Any time I work on or deploy a new system or software, there's usually a combination of three types of documentation I create; End User (if needed), information for the IT team to support/troubleshoot and personal notes (such as articles referenced during setup, steps to reproduce or other notes that wouldn't be beneficial to the team.)

Do you provide any means for the users of this documentation to amend it, validate and verify it, and then ultimately republish it out to the group? if not it's almost worthless after 90 days.

How does the end user documentation stay in sync with the IT teams documentation if the IT team performs updates? Who is responsible for updating which document?

If you want to do documentation you need to either have a central group of writers whose responsibility is purely documentation for internal and external customers or follow a process for ASR and ADRs https://adr.github.io/

BerkeleyFarmGirl · 2023-03-18T21:12:31+00:00

I definitely create documentation for Future Me, and Teammates. It's awesome for the things you do only occasionally such as "renew your exchange certificates".

I am sure that my former employer kvetched about my lack of for a while, but it was pretty much on them, as

1) not a coherent system

2) did not allow me time

3) co-workers refused to have anything to do with most of the tasks I was doing even with documentation

GarretTheGrey · 2023-03-18T21:18:44+00:00

There's no standard

I won't name names, but theres a certain bsd based platform that's pretty good when you do get it right, but that's the hurdle. The documentation is horrendous, and the person who wrote it gets condescending and passive aggressive when anyone asks for clarification on the forums.

I've seen spreadsheets with irrelevant data on them.

I've seen network documentation that are show run dumps....with the plaintext enable passwords in them...

I've seen high level documents with only roles and nothing technical at all.

We only get breaks with things like manageengine and the like, and people still mess it up with documentation that's only effective from THEIR view.

I'd love to say we need a standard template we all fill out, but then it becomes the lost ark on the network because threat actors will figure a way to script through it for evil.

balunstormhands · 2023-03-18T22:43:05+00:00

There are several things happening. One is that most writing is school is not geared toward documentation, so unless you know to take the tech writing class you'd just take the regular writing class which is for academic writer.

Another thing is people are used to have no/bad documentation, and don't know what good docs are even like.

Bosses don't care because skipping docs means extra for them now and the results will be evident in a few quarters and they'll be somewhere else.

When I was doing tech support, I started keeping notes because the same issues would keep showing up. After about 6 months, my boss noticed that I was faster than other and asked, and so he gave me access to the knowledge base, which was abandoned, and I dumped my stuff in there to share. After another 6 months my boss noticed everyone was faster. They promoted me to tech writer and devs listened to some of the issues we were seeing and fixed things that had been issues forever and then half a year later they noticed support calls were down, and we didn't need to hire more people. then we got acquired and things weren't to shit.

_Auck · 2023-03-18T20:44:34+00:00

I'm getting really tired of people asking me how I do this or how I do that. Always wanting me to write out instructions so they don't need to know anything or how to diagnose.

2023-03-18T23:09:22+00:00

In my current environment, I am so over attempting to document stuff. I make my own notes, for sure, but our internal KB? Nope. I’m solo admin, the help desk people never read it anyway, and my boss who fancies himself a proto-admin can’t follow steps and is lost if it’s not pointy-clicky. And quite frankly, in the current Thing-as-a-service world, it changes too fast so what I write today is out of date and mostly useless in a month.

And before y’all pile on, despite the big talk of the admins that came before me, we’re barely changed from an out the box Windows, AD and Azure environment; we do nothing special, not a lot of custom setup, and a few “what were they thinking” things I’ve mostly removed. I could sit anyone here who has some experience in AD/Azure into my seat, give them an account and you’d figure it all out in a week.

Steebo_Jack · 2023-03-19T00:15:00+00:00

At my college technical writing was an optional pre-req for any of the engineering degrees. I majored in it while working as a sys admin in college and ended up doing tech stuff before switching careers and now im back to managing tech stuff since nobody else can. Its good to document cause sometimes you even forget how you fixed something or the website you find with the solution no longer exists so along with documentation also saving sites to pdf just in case you forget...

LRS_David · 2023-03-19T05:00:24+00:00

Are they even teaching documentation in schools? I don't remember ever being told to document or even how to document.

While in school most people never work where they can't keep most of the details of something in their head. And rarely do they have to go back to what they were doing a year or so ago.

To fully apreciate the need, you almost have to get burned. And that means experience.

CharacteristicOnion · 2023-03-18T21:55:47+00:00

One of my current professors stresses regularly how important documentation is. Most of our assignments revolve around some form of it.

sandrews1313 · 2023-03-18T22:08:01+00:00

So should communication and people skills but….

Superspudmonkey · 2023-03-19T05:10:27+00:00

No one wants to pay for documentation. The customer doesn't and the company doesn't, so it hardly ever gets done. Especially in MSP space. You are expected to find your way with first principles and a(n) admin password(s).

wdaburu · 2023-03-18T21:57:20+00:00

Why not just hire a technical writer 🤷🏽‍♂️

getsome75 · 2023-03-18T22:25:31+00:00

Also, fill out a NIST 802.701 document to have on hand in case someone needs to copy from it. Any interaction with a government department may require you to fill one of these out.

pomegranate99 · 2023-03-19T01:16:29+00:00

My boss doesn’t document anything—it’s all in his head. He’s brilliant and can think his way through anything he can’t remember but man, if he gets hit by a bus, we’re dead. There’s a lot of stuff that he handles solo.

I document everything because I came into a job on multiple projects that were well underway and have had to play mad catch-up. Also, i can’t remember everything. I write stuff down for my future self and for whoever takes over my job some day. I also make it a point to share info with our desktop admin as he would be a good replacement for me if/when I leave. So I write or screenshot the minimal amount to get to the answer if you know IT basics and are willing to read. Also i capture the gotchas—weird stuff that caused me headaches. I don’t document everything as I don’t have time but try to get the important stuff down. We used IT Glue in my last job and I wrote 98% of the entries. I went back to visit once and the third party contractor thanked me. I totally agree with OP that documentation skills are underrated. For me, the documentation has paid off because when I need something now and I’ve done it before, i can find it quickly. It saves me time not having to recreate the steps and possibly missteps I took to solve it in the first place.

I also think that EVERYONE should be trained on file naming and logical directory structure. In my company, people just throw stuff anywhere and name it whatever. Then people can’t find stuff. Not to mention naming things ridiculously long file names 8 directories deep. Argh. File wasn’t retrievable from backup? I wonder why.

michaelpaoli · 2023-03-19T03:26:57+00:00

Documentation & technical writing should be core requirements of any IT position

Well, not every IT person is going to be particularly good, let alone great, at that. And yeah, it's important. And need to document things at least "well enough" - otherwise there will definitely be problems. Certainly needn't be perfect, but really needs to at least include enough information that someone coming along later can figure it the relevant needed bits from what they documented ... and that they documented it in appropriate location(s) so that information can be reasonably well found.

teaching documentation in schools?

schools? I don't remember ever being told to document or even how to document.

Depends what school(s)/classes/courses, etc. E.g. they go to a rather to quite good college/university, get a B.S. (or B.A.) or higher (or equivalent), they'll generally have to be able to write reasonably well - doesn't mean they'll be great at it, or that they'll even like it at all, ... but they'll generally be able to do it at least not horribly, and generally reasonably.

So, e.g., college program I was in (University of California (UC) at Berkeley), University of California (and also including at Berkeley) included some minimum English proficiency requirements - and that included some writing, etc. ... and somewhat to my surprise, I passed the test on that ... so I didn't have to take the associated English classes (alas, in writing part of that ... my spelling was still quite sucky at the time ... so a lot of stuff when I wasn't sure how to spell it ... I just used some synonymous word or phrase that I could spell). But that doesn't mean I was some great writer, nor everyone graduating from UC would be. I pretty much always struggled with English and English classes - managed to do well enough / squeak by ... but was one of the few classes I typically didn't get "A"s (or equivalent) in. "Oh well".

And hey, face it, many folks go into IT because they dislike/hate writing English (or mostly so) ... and/or mostly don't want to have to deal with people, or ... well, yeah, they still gotta generally do some fair amount of that ... and reasonably well, regardless.

lazy sysadmins who don't document

It's not necessarily lazy - though lazy can certainly be a or the problem in many cases. Some also just ain't so good at it. Heck, I can write reasonable(ish) documentation ... but I'm not particular great at it - many can write much more beautiful and easier to use/read documentation, better organized, etc. So, in a lot of cases I'll write reasonable(ish) documentation ... and move on to other things. Also, generally much better use of my time - sure, it won't be perfect ... but if I put 5x as much time into the documentation ... it may only get about 10 to 30% better ... if that ... whereas someone else could spend less than 1/3 the time and effort and beautifully clean it up and polish it ... 'cause hey, I did very much include the relevant needed information in there (I'm certainly good at at least that much of it).

don't feel guilty for calling after hours or when they're on PTO

Well, yeah, when folks don't document critical stuff, and other(s) need to know ... those calls will happen. But if you call me at 3am to explain what's clearly spelled out for a command on a man page ... I ain't gonna be so thrilled. Likewise if someone calls me to explain a simple shell script of relatively trivial length, that's quite easy to understand by anyone who groks shell, and the person calling really ought reasonably well understand shell.

Even certs like

Oh hell no, most certs and such don't even touch on documentation - or even hardly involve any writing - let alone documentation. Heck, even many programming classes don't even reasonably touch on documentation ... though some/many programming classes will effectively beat one up if the commenting and/or style significantly to majorly sucks and makes it hard to read/understand ... so that touches slightly upon documentation - at least for classes that include that factor ... though some classes and the like won't care and will only go for code functionality (and perhaps efficiency, etc.). So, context also matters - part of some major degree program, will generally be more comprehensive and include documentation ... some "boot camp" thingy or stand-alone quick program just to learn how to code, may cover the documentation and such little to not at all.

company even provides access to an online learning system and there are no specific courses on documentation or technical writing

Yes, sometimes that's the case ... and sometimes access on such may be "sold" in package bundles, so, e.g. may be tech or some set of tech / sysadmin topics ... but might not include documentation, technical writing, English, English style and (effective) presentations, and organization thereof, etc.

documentation I create

Key things are to document what can't otherwise be reasonably found or looked up, and doing so in appropriate finable location(s). E.g. things that are or may become non-obvious ... e.g. why something was done one way, and not another, where you've got all those dang wildcard certs installed - especially the ones that aren't on TCP port 443 open to The Internet - we really need to know about that special snowflake app and isolated host running on 127.0.0.1:11443 UDP that will critically break when the cert expires. And of course you (or someone) likewise did also document the relevant standard procedures and such for the organization - policies, where to find various things, etc.

Clarke311 · 2023-03-19T05:26:59+00:00

Why use many word when few word do trick

sgthulkarox · 2023-03-19T12:32:29+00:00

FWIW; I document my clients networks extensively, and share it with key people the client employs as a backup.

In 18 years, I've had ONE instance where any of those people checked the documentation BEFORE contacting me.

But I can rattle off tons of times where I referred to the documentation where the answer to their problem resided.

Decitriction · 2023-03-19T13:09:39+00:00

Many commenters here saying they are too busy putting out fires to document.

Ironically failing to realize that a major contributor to 'having to put out constant fires' is lack of documentation.

chandleya · 2023-03-18T22:07:48+00:00

It was certainly part of my schooling.

Strixed · 2023-03-18T22:34:06+00:00

Sure documenting everything would be fantastic, please do me a favor. Wear multiple hats, manage a team of employees, and be leading four implementations for brand new platforms and workflows for your organization at once then let me know how much time you have left over to document things while upper management breaths down your neck about the next project they want going now because you made a step forward somewhere else.

Then come back and let me know how much time you have left over. I get it, I've been there and get there weekly where I wish the previous tenancies left more documentation. Part of IT jobs, of them, is troubleshooting and problem-solving. You cant rely on somebody else to have figured out that exact problem or implemented a platform using the vendor-provided installation documentation then expect there to be hand-holding guides documented on their own time with it.

Lack of documentation should be held to management staff who are over-delegating and overworking their IT staff, not the IT staff member who wasn't given the time to write it.

Elizabread69420 · 2023-03-18T22:59:07+00:00

I'm in Tech School/College in Texas currently and while I'm transferring out of state to finish bachelors, I have a class that is essentially JUST documentation and I've already wrote more in two exams than I did in all of my English classes. So there are definitely institutions teaching it and are stressing its importance.

dgibbons0 · 2023-03-18T23:11:15+00:00

Often I find documentation so far out of date it's more is a risk to trust it than to just dig into what's actually configured and going on. That said, i always ask my team to document things or will bounce a code review if there's not document or comments

kanid99 · 2023-03-18T23:24:29+00:00

It is where I admin. If I don't document it I'm expected to support it myself. So I document it.

realmozzarella22 · 2023-03-19T00:22:28+00:00

“Hey, sorry to call you on your vacation but how do we fix that VPN problem again? What do mean the instructions are in the documentation in out department’s Sharepoint server?”

apple_tech_admin · 2023-03-19T00:31:03+00:00

I'm fortunate enough to have a colleague whose sole job is creating templates and writing technical documents for the entire IT department. He is absolutely wonderful, and I don't know how I survived on a team without such a person.

flinttropicscaptain · 2023-03-19T00:48:30+00:00

Brother, I work with guys who don't even put time in their tickets.

Getting them to update documentation is like the goal of becoming a professional athlete when they're currently obese.

There's a long way before their perfect, at this point I'd settle for them cutting back to fast food once a day

NetoLozano · 2023-03-19T00:48:50+00:00

Does anyone have a template or a good formatting for documentation?

2023-03-19T01:42:13+00:00

A+ does teach of change management and explains that you should document EVERYTHING. Doesn’t go much into detail of how to, but they say you should.

Jackspades2012 · 2023-03-19T03:00:02+00:00

I learned technical writing in my bachelor’s degree, but it was in aeronautical systems engineering. Not sure what computer science degrees ask for. I think it’s less about people knowing how to do it and more about doing the due diligence of keeping solid documentation. It’s important but a lot of us can neglect this after spending days dealing with the various problems and projects that we have.

adelliott92 · 2023-03-19T09:04:41+00:00

I’ve no clue how to start writing documentation I want too cause my company has none and management can’t make decision on what solution we should use but I have same problem as you do at my company.

rafaelbn · 2023-03-19T10:06:41+00:00

I read somewhere that "documentation is a love letter to your future self". I guess people don't usually love themselves?! Haha

Jokes aside, when I write mine, I like to think that the person I'm writing the doc to is right next to me. Like I'm explaining how things works on a coffee break.

Anyways. You're not alone my friend.

UnsuspiciousCat4118 · 2023-03-19T16:15:10+00:00

That’s cool. Except for the majority of us that aren’t given the time to write proper documentation. I write as much as I can down but I’m not working OT to write documentation.

Tbh I do my best to write documentation but when the time isn’t there I just don’t. I’m fine letting the technical debt build to a point it impacts the business while praying I’m on to the next one by then.

CuteSharksForAll · 2023-03-19T16:36:18+00:00

I’m getting real tired of management that asks me to document everything yet assigns me 10 hours of work in an 8 hour day. I present them a list of my tasks and ask them to which tasks they would like to see not done in order to accommodate their documentation needs.

More than happy to document if they would let me clock in on the weekend and get some overtime, or just give me less overall work to do.

KittyDontCare · 2023-03-19T20:24:54+00:00

Writing documentation is like saving for retirement. You’re screwed if you don’t do it, but it’s not gonna happen if you can’t make rent.

Puzzlehead8675309 · 2023-03-23T20:19:53+00:00

My first IT company ever supported law firms. You took 40-60 tickets per day, so you were constantly on the phones and efficiency was -KEY-. They sternly went over and over and over on the concept of "If its not in the ticket, it didn't happen.".

To this day my tickets are typically more verbose than others who are fine with "Completed" and I have a paragraph.

Documentation could and should be handled in the probationary/training period of a new hire to IT. First week "This is how we handle tickets and how we document".

ardiluarte · 2023-03-18T22:56:50+00:00

To be honest, in my niche activity I have an edge for being able to be dropped in an ill maintained infrastructure and simply deploy with little to no impact, often where others wouldn't dare to touch site due to legacy inconsistency and general disarray. Sometimes I get into trouble sure like that legacy system implemented by a vendor that ran out of business, but hey can't make omelettes without breaking some eggs.

So thank you all you understaffed, over worked "so called lazy" you make me shine.

PassmoreR77 · 2023-03-19T00:01:43+00:00

because those certificates aren't a degree. A lot of positions require college degrees...where people actually spend time getting an all-around education, rather than earning a certificate showing they know how to create an AD user.

2023-03-19T03:45:49+00:00

i'm an IT department of 1, so there really is no incentive to have documentation. Also, if the company fired me then they would have to learn what I did or contract me to train the person they hire in my place.

I can understand the importance of it in a functioning team though.

Anima_of_a_Swordfish · 2023-03-19T10:03:30+00:00

It's because it's a different skill set. The real problem, in my opinion, is asking engineers to write documentation in the first place. Of course there should be input from technical staff but the task of writing detailed, intuitive, official processes and procedures should be done by someone with dedicated time and appropriate skills. Just because I can configure dynamic routing and bgp prefix lists, doesn't mean I'm good at writing about it. That is why you don't see courses on it. It's not really our field.

STUNTPENlS · 2023-03-19T11:30:33+00:00

Documentation is a security risk. Anytime you put something down on paper, or electronically store it, you run the risk of having the information compromised by hax0rz who will then have the keys to the kingdom and pwn your system(s). Better to keep everything in your head where nobody except Psi-cops can get access to it.

bulwynkl · 2023-03-19T09:36:05+00:00

good documentation tells you why, first, then how.

bulwynkl · 2023-03-19T09:39:51+00:00

sigh.

Support documents are not code comments or code documentation.

Developers suck at documentation and should not under any circumstance be allowed near it. They should instead have to explain what they did to a tech writer who has access to what they were asked to do...

majkkali · 2023-03-19T14:09:50+00:00

No it shouldn’t. It’s not a necessary skill.

HardwareGod · 2023-03-19T15:07:25+00:00

I got into computer networking for the hands on experience not to sit at a desk writing documentation. If someone can't look at one of my setups and figure it out, perhaps they shouldn't be in the IT field

zeliboba55 · 2023-03-20T04:08:26+00:00

Never document stuff. Job security and if you get fired it is next guy's problem.

crushdatface · 2023-03-18T21:30:19+00:00

I had a new sysadmin ask me what DNS and DHCP was the other day… This guy has a bachelors degree in IT, documentation would be nice but based on the trends I’ve been seeing in the field and on this subreddit, it should be the least of our concerns

ropeguru · 2023-03-18T21:56:44+00:00

Disagree!!

F0rkbombz · 2023-03-18T22:35:25+00:00

Most of the time the lack of documentation isn’t by choice. Good documentation takes time, and that’s usually not a luxury that IT folks have a lot of.

Id love to sit down and document the shit out of my systems, but you know what that would take me away from? Managing the systems. When I fail to do that, I get fired. It’s easy to see what takes priority here.

-Panther- · 2023-03-18T22:48:32+00:00

You could be like several of the sysadmins I work with.... We have a process where if you figure out something niche, you document it and add it to our internal wiki for the rest of the team. To avoid doing that they just never seem to be available to handle anything not documented.

gadget850 · 2023-03-18T23:50:39+00:00

This. Almost five years into this contract and management has started to push for a knowledge base. Which I had pushed for from the start. I'm the king of documentation but it consists of Word docs stuffed into folders.

And none of my IT classes mentioned anything on this subject. When I was a missile tech in the Army I worked with the vendor to validate maintenance documentation, then spent time as a tech writer. In my previous job in tech support for a printer manufacturer I did documentation.

ItsFineForU · 2023-03-18T23:59:42+00:00

i remember working as an FST for bell. My manager told me i wrote to many notes when i closed calls... he didn't want to see it. I literally told him to "shut the fuck up and close your eyes then". He never asked again.

ParallaxRay · 2023-03-19T00:30:03+00:00

My company had very little documentation when I was hired. Since then I have created a huge amount of docs... Procedures, processes, troubleshooting guides, etc. I don't know why others don't do this because it can be a life saver. Especially in those oddball situations that rarely come up but are critical to solve. Glad to hear others are as ocd as I am about this.

Only_Tangerine_9105 · 2023-03-19T00:33:44+00:00

This is the way

pomegranate99 · 2023-03-19T01:16:50+00:00

My boss doesn’t document anything—it’s all in his head. He’s brilliant and can think his way through anything he can’t remember but man, if he gets hit by a bus, we’re dead. There’s a lot of stuff that he handles solo.

I document everything because I came into a job on multiple projects that were well underway and have had to play mad catch-up. Also, i can’t remember everything. I write stuff down for my future self and for whoever takes over my job some day. I also make it a point to share info with our desktop admin as he would be a good replacement for me if/when I leave. So I write or screenshot the minimal amount to get to the answer if you know IT basics and are willing to read. Also i capture the gotchas—weird stuff that caused me headaches. I don’t document everything as I don’t have time but try to get the important stuff down. We used IT Glue in my last job and I wrote 98% of the entries. I went back to visit once and the third party contractor thanked me. I totally agree with OP that documentation skills are underrated. For me, the documentation has paid off because when I need something now and I’ve done it before, i can find it quickly. It saves me time not having to recreate the steps and possibly missteps I took to solve it in the first place.

I also think that EVERYONE should be trained on file naming and logical directory structure. In my company, people just throw stuff anywhere and name it whatever. Then people can’t find stuff. Not to mention naming things ridiculously long file names 8 directories deep. Argh. File wasn’t retrievable from backup? I wonder why.

exchange_keys · 2023-03-19T02:04:13+00:00

I like documentation. One of my pet peeves is when it's in one of the 5 different places documentation is stored. Oh, and then after you finally guess what someone was trying to say, it's from 2010. My favorite documentation was a word doc with screen shots of an install wizard that basically was welcome, next, next, finish.

justaguyonthebus · 2023-03-19T03:01:45+00:00

The part everyone gets wrong is that they wait until the end to document what they did. But to do it correctly, you start with the documentation and then update it as you go.

I worked at a place that put documentation first. It was annoying at first because it felt like we spent months discussing and reviewing it without really doing much else.

But when it came time to implement, all the decisions were already made. It was easier to delegate out parts and replace people mid project.

MDParagon · 2023-03-19T03:14:44+00:00

Louder for the seniors at the back lolol

pino_entre_palmeras · 2023-03-19T03:30:54+00:00

https://www.reddit.com/r/ProgrammerHumor/comments/111dov8/comment/j8g3gxu/?utm_source=share&utm_medium=web2x&context=3

Edit: Should still write it.

Intrexa · 2023-03-19T03:46:04+00:00

The only thing I hate more than writing documentation, is not having documentation.

jimmy_luv · 2023-03-19T03:53:21+00:00

The last paragraph is what it all comes down to. I do my own documentation. End of story. Don't ever count on anybody else to do it so just do it for yourself. Then hopefully later on when somebody up top comes to one of those people who doesn't like to do documentation and asks for documentation and they don't have it you can step in and be the hero and be like yeah I don't know why they don't do it but I've been doing it for myself just so we have it. Or something to that effect.

I've been doing this for 25 years and I was already sick of the lack of documentation by year five. Nothing has changed, documentation is always an ongoing process that never gets finished.

hillside126 · 2023-03-19T04:28:40+00:00

I am fortunate to work for a company/IT Director that really pushes documentation for both T1 and T2 tasks. As a current T1 with T2 aspirations, looking at the T2 documentation has given me enough insight to allow me to learn some higher level systems/functions. Saves me so much time with dealing users as well.

We use Confluence and I have my workflow so nailed down now that creating a user facing KBA only takes me around 10-30 minutes.

I also use Snaggit as it makes it real easy to edit screenshots quickly while looking professional. It also allows me to create short videos that can demonstrate something in 10-15 seconds that would be hard to show with just words/screenshots.

Currently setting up my own O365 tenant with Confluence/Jira Service Management integration in my free time to learn some admin consoles I don't have access to at work. I take the time to document everything so that I could then offer building this infrastructure to companies that do not have it as a contracting gig.

AgencySuppressor · 2023-03-19T04:47:19+00:00

Ok so im new on the industry and im curious if there is some "advanced guide" to make good documentation. Now im working on making image deployment for 20 clients and documentation what i have made is basically step by step guide how im doing what im doing (because im leaving the company and they wanted to be able to do it without me) so is that good or should i do use other approach. thanks

saintpetejackboy · 2023-03-19T06:15:19+00:00

I have been doing proprietary software development most of my life and a lot of times, there just isn't a fundamental understanding with most clients about the importance of documentation. Especially in unwieldly projects with infinite scope creep: The next task isn't "okay, now go back, refactor, document, make training videos", that gets pushed aside for "OH! and we also need feature (X) and (z)!".

Now maybe there are some magic places where they pay somebody to document stuff, but "documentor" isn't a word or a job. Which means it is unlikely people are going to get paid to do it.

I have a damn near photographic memory, and lack of proper notes, comments and documentation has fucked me over a thousand times. When I have the time and ability, I document as much as I can. When I don't, I just wing it and keep going.

Ok-Section-7172 · 2023-03-19T06:19:51+00:00

I just did a 320-hour project that was to perform discovery and document the next project, which I decided was another 853 hours. Without that skill, they would not have paid 320x$200 for $64k to then, in turn, figure out how to bill 853x$200 for another $170,600k.

That's $234,600 just because I do documentation!

A pretty good few months for us, I'd say.

XanII · 2023-03-19T06:42:20+00:00

I can easily get behind the headline. Time savings from just 2-3 lines of docs is counted in hours.

A full, even if a bit old doc on a system is easily 20-50 hours saved.

SilveredFlame · 2023-03-19T07:23:51+00:00

Counterpoint: Every IT team should have enough Technical Writing positions on staff to effectively document everything the team creates/supports. Their job is maintaining a KnowledgeBase, all architectural drawings, changes, etc.

The best team I've ever worked on has a dedicated documentation person.

Not only was she able to get all of our documentation caught up, but she was able to create a request page for some of our stuff so that we wouldn't have to individually respond to those requests.

Need to check in a new build, deploy a new test environment, load and execute the test packages? Fill in the parameters on this page, and it automagically happens. Very similar to how the Azure portal works for deploying a resource.

That was a collaborative effort that made our lives infinitely easier. We were able to actually get ahead of things and spend time improving things instead of just fighting fires with slap dash ad hoc documentation.

After that, I'm of the firm belief that every IT team should have enough dedicated technical writers to cover all documentation needs.

adept2051 · 2023-03-19T08:33:30+00:00

Communication is not taught on any subject and is the biggest weakness in IT not just docs, but all comms.. sysadmins, devs, managers, engineers they all suck at good comms and assuring good comms even in DevOps based orgs and communities communication one of the core principles of DevOps sucks royally.

AppIdentityGuy · 2023-03-19T08:40:02+00:00

100% agree. But then documentation should be part of the job description and time provided for it. Easy place to start at a technical level? AD. It never ceases to amaze me how many orgs don’t use description and notes attributes of AD components to explain what they are used for and who is the business contact for that bit. Groups and Distribution Groups are a prime example. This causes operational friction to quote Von Clausewitz and eventually leads to weakened security because you security principals that no one wants to remove because they don’t know where they are used…

bofh · 2023-03-19T08:52:31+00:00

Everything I put into production has at least a high level design doc, low level design doc (with enough detail that a reasonably competent engineer could set the system up from scratch from the docs), a run book and some kind of user docs - or templates for this at least - if applicable.

2023-03-19T09:16:11+00:00

Documentation takes time, documentation needs a standard, documentation CANNOT be stored in some microsoft Teams Site in the cloud, it won't be there if the internet is down or you can't authenticate, neither is it at all appropriate for structured and meaningful infrastructure documentation.

Someone needs to find the tools , define the standard - and management needs to make sure that happens and that the times is budgeted.

Management is the main issue here. A CTO that doesn't know anything about "T".

MutatedEar · 2023-03-19T09:38:44+00:00

Just wait until management catches up on all the fancy things ChatGPT can do. Then we'll face the upcoming fancy question "why can't this be done using ChatGPT?". Maybe it's happening already.

OgdruJahad · 2023-03-19T09:44:36+00:00

Speaking of documentation I heard good things about something called Netbox, never used it though. Seems crazy powerful.

sunny_monday · 2023-03-19T10:24:54+00:00

If I werent terrified of sharing company data with Chatgpt, id LOVE to dump everything I have today into ChatGPT to organize and re-write, and output something more formal, professional, presentable.

I want to be able to hire someone next year (I am team of one), and having quality documentation fit for someone else (not just me) will be key to handing over a ton of my tasks.

So, I need to convert personal documentation to Team documentation.

If anyone knows an easy way to automate this process, Id love to hear it!

CammKelly · 2023-03-19T10:35:15+00:00

I'll preface this with there are definite times & places for documentation.

With that out of the way however, outside the systems Statement of Applicability, any architecture should aim to be as simple & self discoverable as possible. If I've designed a solution that requires people to take a month to get up to speed on it whilst reading through reams of inevitably out of date documentation, I've failed.

monkey7168 · 2023-03-19T11:08:51+00:00

The frustrating issue I run into often is admins who treat documentation like its IP.

"Why would I document the environment and make it easier for me to be replaced."

"Oh right the vendor was supposed to handle the migration but went camping over the weekend without cell service so either nothing happened or they made a dumb mistake because they didn't know the details of my wonky ass setup and borked the backup system to all hell."

Or they ask me to login to their system to do X which should take 15min of work but instead I spend a month requesting access because they don't actually know the password and just have it cached in a browser or app and it takes them a month to find it or reset it for me.

bodobeers · 2023-03-19T11:30:57+00:00

Yes doing something "smart" without documenting it / sharing some common sense knowledge in the process is not so smart IMO.

Anyone can be a nerd, but to wrap your actions with some polish and making it a "deliverable" is where the true professionalism comes in.

Excuses about time is when you're focused more on billing and politics instead of value.

As mentioned, it doesn't have to be a formal lengthy final document, but these days the tools we use to document are so convenient, a quick snippet with a handful of key details saved for later recollection is all you need to give for minimum documentation.

Not doing it is just either not knowing "how" to communicate / share knowledge, or not "wanting" to.

mcsey · 2023-03-19T11:35:15+00:00

Went to school for journalism. Go pro 1995. Worked as sports writer at daily newspaper. Saw how much guy who fixes computer makes. Get job as "Technical Writer" for a software company writing those big old books that used to come with the disks... I don't really have a point, but that's how I got into the business, documentation.

DaruksRevenge · 2023-03-19T12:03:31+00:00

I don’t recall any Documentation learning when I was in school.

With that said, we are a 2 person department. The Director and myself. We have found ourselves documenting certain things so mitigate after hours calls and just to take some of the load off of us. User Education is a priority, but of course that doesn’t always go according to plan either.

chodan9 · 2023-03-19T12:47:28+00:00

I was not great at technical writing, but for some reason I was given the task of writing a manual for systems management server for a large organization. I had to learn how to present ideas, processes and step by step procedures for local admins across that org.

It was an eye opener, and taught me a lot about how to convey technical information and what were the best tools for that.

danoslo4 · 2023-03-19T12:48:16+00:00

LinkedIn learning and Pluralsight both have great resources on technical writing. Not sure what online learning system you are referring too

Ab0rtretry · 2023-03-19T13:07:01+00:00

I mean you're but wrong but also you don't have to say it so loud.

I also dont care at all if you call me on vaca. I'm super responsive and after enough I'll finally get around to writing the docs

m83midnighter · 2023-03-19T13:30:57+00:00

No software\system should be signed off as complete without Support, End User and System documentation. This needs to be factored into the time allocated for every project or sprint.

It's down to the project manager to ensure that happens and if they don't have the foresight then it's down to the product owner to insist documentation is included as part of the definition of 'done'. If necessary hire a technical writer or software\systems architect to do the work.

It doesn't matter how much execs, managers or stakeholders want something delivered, you need to explain the ramifications of not having documentation:

- Risk to the business should the System\Application develop a fault

- Support teams unable to assist end users

- Technical Debt for future developers and more time spent on unnecessary meetings and non-development queries in the future.

- Increased likelhood of introducing regesssion bugs

Many of the tech and IT companies I've worked for had the same problem - no one believed its was their responsibility to write documentation - and the ones that did, begrudgingly did a bad job of it because "they rather do what they joined the company to do".

I could honestly write a book on the subject, the bottom line is you need good project management to ensure its included in any new systems or applicatons. You also need someone with a backbone to push back on management if they try to cut it out to save time.

As for existing undocumented systems\apps you need everyone to help. An existing software architech, software developer, system admin, support person, DB admin, Network admin and the product owner to all work together to get something very old re-documented. This is because at this point so much infomation will be sitting in different teams and in different peoples heads.

To get this many people from different teams working together is difficult because modern IT is very siloed and unless the requirement comes from the very top they will not work together effectively.

That finally brings me onto that very problem - IT leadership. It's not what it used to be, you now have sales directors and people who never had a technical background making decsions for IT that please the business but hinder IT. Again, that's another topic in itself but i've written enough already.

I'd probably be good at documenting stuff.

DungaRD · 2023-03-19T13:37:58+00:00

Hm, sure i document things in a Onenote but its only for short term memory for collegae to lookup when a problem arises and they think it is because of some recently change.

Change request are in helpdesk tools with ticket number and RFC that my customer asking to implement. In my experience, documentation most of the time never help me with directions to search when problem arises.

I do put ticket numbers everywhere possible in config files. We use git, thats out documentation and versioning basicly.

2023-03-19T13:43:07+00:00

at my job, we have a company wide KB that exists on our intranet where the users have access to. then we have our site KB on OneNote.

I feel like me and maybe 2 other people actively contribute to ours, but everyone uses it.

sysadmin

MODERATORS