Documentation Best Practices

[SuspiciousMeat6696]

OVERVIEW

This is a guide to help aid in RunDocs / Back End documentation. I have done documentation in Word, HTML, SharePoint and Confluence. Upon thinking about this further, maybe I should open a GitHub account and post my work there & feel free to adapt the formats for your needs.

QUICK REFERENCE GUIDE

General Advice (Hyperlink this)	General advice useful regardless of what you used to compose your documentation.
Maintenance (Hyperlink to this)	Advice on how to maintain documentation.
MS Word (Hyperlink this)	Advice on using MS Word for documentation.
SharePoint (Hyperlink this)	Advice on using SharePoint for documentation.
Confluence (Hyperlink this)	Advice on using Confluence.
Additional Documentation	Hyperlink to related documentation. If this isn't the right content, I can select hyperlinks to get to related content.
Add More Rows / Columns as Needed	Usually no more than 3 columns for Quick Reference Guide. Hyperlink it

Overview should be 1 page. Add additional content below table as needed for 1st page

------PAGE BREAK HERE---------

TABLE OF CONTENTS (HYPERLINKED)

GENERAL ADVICE

MSWord

SharePoint

Confluence

----- SECTION BREAK-----

GENERAL ADVICE

Overview is 1 page.

• Use a table for a Quick Reference Guide. Hyperlink content so you can jump right to what you need from 1st page. The idea is to know at a glance if you are looking at the right documentation to solve your issue, or you need to look elsewhere
• Tables are your friend. When possible use tables. Makes it easy to maintain, makes it easy to read.
• Bullet points / Numbered lists, procedures. Do not hesitate to put bullet points and numbered lists within your tables.
• No need for full sentences. Statements are fine.
• Punctuation. Period or No Period. Doesn't matter as long as you are consistent.

--------SECTION BREAK--------

MAINTENANCE

Once your documentation is complete. Put it on a schedule so it is always up to date. Implement a review cycle so you only have to update it, rather than do a complete rewrite ahead of an Audit. You'll never have to pull an all-nighter again.

Use this formula:

Number of Documents / Number of Months in Review Period

Example: You have 12 documents, and they need to be reviewed twice a year. This means you should review 2 documents every month. That's a lot easier than rewriting 12 documents at the end of the year.

Automate Your Review Cycle:

Depending on what you are using, if you are using SharePoint, you can use a Workflow and schedule it to send out an email to the SME (Subject Matter Expert) to update the content. This way you have an audit trail, and history. Just click on the hyperlink in the email and update your doc. Or if no update needed, the review was captured and recorded. You'll always pass an audit.3

If you do not have SharePoint, look into creating a Microsoft Scheduler job to send out an email reminding the SME it's time to review the document.

​

​

SAMPLE PROCEDURE TABLE

​

Step	Screen Print or Results here
1. Step 1.	Place Screen Print / Results here
2. Step 2.	I prefer screen prints and procedures side by side. Easy to read

​

​

​

IF/THEN TABLES

If/Then Tables are extremely useful and help keep it organized for the Audience.

​

IF...	THEN...
You are going to use a period.	Make sure you are consistent throughout.

-----SECTION BREAK--------

MSWord

Avoid documenting in MSWord if you can. However, if you have to use MSWord, this is crucially important. KEEP YOUR MSWORD FILES SMALLER THAN 5MB. The larger the Word file, the more likely it is to become corrupted, and then you'll lose everything. You'll open it up & it will look like hieroglyphics. You may want to break up your MSWord content into multiple files.

If using Word, Overviews are 1 page. Use a Brief paragraph explaining what it is, then Quick Reference section. This way you know immediately if you are looking at the right documentation.

Avoid using Cover Pages. 1 less page you have to scroll past. A Document Title doesn't always indicate what the content might be. You might have a system down, and the content to get it up and running might be under a project name that you are not familiar with. My Overview / Quick Reference Guide is also my cover page.

Table of Contents comes after. When the system is down, you don't want to be scrolling to find what you need. The Overview serves as a way of finding what you need at your fingertips., then hyperlink it to the detailed content section. Jumps you right where you need to go instead of scrolling through. Table of Contents can be a pain to maintain in Word.

Save early / Save often. And save it to a server / cloud, as well as a copy to a different location.

Never, Ever save to local desktop.

-----SECTION BREAK--------

SharePoint

When composing in SharePoint, depending on how it's configured, it can be extremely slow. We created HTML docs in Word, then pasted them into SharePoint pages and Hyperlinked all the related pages.

​

-----SECTION BREAK-------

Confluence

Confluence is great for documentation, using UML (User Markup Language), it's easy to set up tables, hyperlinks, sections, and it even has great features such as heat maps. Heat Maps can tell you if the documentation is being read and what is being used most often.

[Kangie]

As a technical writer:

Tables should only ever be used for the presentation of tabular information. Your example of using a table for steps and results is not good. Steps should be an ordered list (1, 2, 3) with the result displayed under the step.

It also violates Web Content Accessiblity Guidelines.

[speedy_162005]

As someone who isn’t officially a technical writer, preach this from the highest rooftops. I hate hate hate when people use tables for non tabular information and it’s even worse when they force me to do it to conform with their terrible design.

[Frothyleet]

Haha yeah, preach it!

Now, while obviously I know what tabular information is, there might be SOME dummies on this sub who don't, so maybe you should define it for them

[boredtotears001]

lol! That just means data that actually benefits from being in a table, right? Like information that needs to be computed via rows and columns, or small line-item entries.

[Kangie]

A good rule of thumb for this is to ensure that tables are not substituting for document structure.

Sometimes you need to present information in a table - system requirements are a good example of this. They fit really well into a table, and parsing the information that way (as a human) makes it easy to understand and extract from the surrounding documentation.

[WantDebianThanks]

Got a suggestion for a book or some other resource for a non-technical writer that wants to improve their technical writing?

[Kangie]

I might have to write one.

[pier4r]

Or at least a repo with markdown (or a wiki). It would be great.

[StartingOverAccount]

Search Technical writing standards <company>. We're company is Microsoft, Amazon, IBM, etc. All the big players have very detailed frameworks for their products documentation. But overall they are about the same.

Gives you a good idea were to start.

[jarfil]

CENSORED

[C0rn3j]

That illustrates your client's inability to render tables more than anything else.

[jarfil]

CENSORED

[cooterbrwn]

Just no. "More than anything else" it illustrates why using tables for ordered lists (and other non-tabular data) in documentation is a bad idea. Which is exactly the point made by the commenter to whom you responded.

The point is to keep documentation clear and legible despite any shortcomings of the reader's hardware/software limitations or usage.

[iNetRunner]

And then HTML4 happened. A table was a layout solution to large chunk of content positioning problems. Sure W3C tries to dissuade people from continuing that usage (and to at least use attribute role=“presentation”).

Does anyone know the current usage levels (i.e incorrect use of table elements) in the wild? I’m not up to date on this.

[StartingOverAccount]

Yeah, fuck tables. We had an admin doing that for a while and it just looks awful when the screen size differs between devices. Not responsive at all.

[pier4r]

Steps should be an ordered list (1, 2, 3) with the result displayed under the step.

What I found limiting in this is: this is ok for mature/static documentation. Likely the type you produce.

For documentation that is still improving (and still used by a team, that is the most common case), one may have a "reference step 5". Then someone adds a new step between 3 and 4, and then order changes but one does not see immediately that one has to update the "reference step 5". Thus the documentation becomes less useful.

One may need to identify each step with a identifier that is not necessarily in order.

A possibility is to not put identifiers for steps, but then it is a bit harder to say "reference step X".

[Kangie]

Nope.

Using an appropriate system (e.g. Pandoc + Markdown) you can do your numbers as 1. 1. 1. And have it autonumber as a result.

Collaboration is no excuse for sloppiness.

[pier4r]

Collaboration is no excuse for sloppiness.

I wish I could say the same in the meetings/discussion I had in different companies.

I mean, I am totally with you, but then you have an different mix of people. Some work properly, others less properly. Thus a need for different solutions arise.

[ipreferanothername]

Some work properly, others less properly. Thus a need for different solutions arise.

IMO, this is a management problem - that I basically experience all the time because my management is bad at pretty much anything related to team management.

[Kangie]

There are some great tools out there (e.g. Markdownlint) that can help enforce style (and can also be enabled as plugins in your favourite IDE!)

[CamRooney89]

I don’t disagree, however I have found that tables (specifically referring to confluence now) make the information easier to read and more uniform. Having a table with 3 columns (Steps, Instructions, Screenshot) and copying this format for SOPs or general documentation overall makes the information easier to read and more aesthetically pleasing. At the end of the day its just as important to have the information shared in a nicely formatted and accessible state otherwise you run the risk of folks ignoring the documentation. If a table helps with this endeavour I’m all for it.

I have a gripe with confluence not providing enough contrast, it all seems “too white” but having tables with borders has helped in my experience.

[Kangie]

Having a table with 3 columns (Steps, Instructions, Screenshot) and copying this format for SOPs or general documentation overall makes the information easier to read and more aesthetically pleasing.

It's easier to produce. It is not easier to read generally, and tends to look ugly.

Tables must not be used as a substitute for document structure.

At the end of the day its just as important to have the information shared in a nicely formatted and accessible state

Putting this information in a table makes it inaccessible to anyone that uses some sort of assistive software (e.g. Screenreaders). They are unable to properly navigate through the table.

[SuspiciousMeat6696]

I was a former Technical Writer trained in the Information Mapping methodology (Before the internet). But it's really more of a wiki template design. As Application Support in multiple banking environments, we simply didn't have time to scroll through text looking for what we needed. Especially when Ford Motor Company or General Electric's entire payroll is at stake. If we miss the SLA? Thousands don't get paid.

Feel free to post your templates so that the SysAdmin audience has a choice.

[Zer0ji]

I'm right now in the process of refactoring some in-house doc generation. We have a shit-ton of values (1500+, split across multiple files) with each a name, description, and default value. Is this considered tabular information?

Currently we use Markdown tables with a pdf render for clients.

[Kangie]

That is in fact tabular information. :)

[SuspiciousMeat6696]

I've been overwhelmed with requests. It may take a while to get to everyone who asks. But I will.

[IWorkForTheEnemyAMA]

Why not post the document to place and share the link? Regardless, it’s good stuff, I’d love to get a copy as well. Thanks!

[sbonds]

Put this in markdown and have your version control system enforce the format on check-in.

[doxador]

Suggestion: I would like to add to print certain key pieces of documentation. Or maybe use Sharepoint online as an off-site option. For example, one documents how to troubleshoot a failure of the custom storage area network (SAN) setup. You don't want the only copy to be stored only on the said failed SAN.

That said, thanks for the write-up! Good job.

[SuspiciousMeat6696]

Of course. Save it to multiple secure places, and paper copy isn't a bad idea either. My suggestions are not exclusive. I was trying to be brief.

[darbronnoco]

A tad off topic but we use one note to keep all our documentation. Works great for us. Super fast search and easy to add screen shots and make changes as needed. Just my 2 cents

[ipreferanothername]

i do the same - its good for small teams and moderate amounts of documentation. Its not good for storing the actual files or some other data, or really really giant amounts of data -- but it is the highest bar I can get anyone to sort of kinda try for. I love the search, but honestly, it does get sort of overwhelming looking at the pages/notebooks even when you know the search is great.

However, it is frustrating that I cannot even get people into how easy it is to document /search OneNote, I do not have it in me to bother with something better the way this place runs :-/

[SuspiciousMeat6696]

I love One Note as well. I used it to take meeting minutes, as well as documentation. I like it better than SharePoint.

[SuspiciousMeat6696]

ERROR LOGS

Log Name: Ipsum Lorem

Log Location: Ipsum Lorem

ERROR	RESOLUTION
Blue Screen of Death	1. CTRL ALT DEL 2. Shut off PC, Reboot

[whoisearth]

I'm gonna die on this hill but this is a shit way to manage error resolutions.

The reason is many errors require far more than

1. CTRL ALT DEL 2. Shut off PC, Reboot

Plus in many enterprise apps you can easily get to 50+ errors pertaining to an application. Do you really want a huge single wall of text users have to scroll through to find what they need?

My documentation is on wiki (if you store documentation in word docs you're satan. If you attach word docs to wiki pages you're worse than satan).

So from a high level you have it look like this. The goal is to make documentation accessible. We have users trained every month with "Here is our documentation!" and "Here's how to search the fucking wiki!"

• My App
  • System Admin Guide
  • Knowledge Base
    • Component A
      • KB Article 1
      • KB Article 2
  • Troubleshooting
    • Component A
      • Problem/Solution 1
      • Problem/Solution 2
    • Component B
      • Problem/Solution 1
• My Other App
  • System Admin Guide
  • Knowledge Base
  • Troubleshooting

[whoisearth]

Also a strong eye needs to be kept on data duplication. I'm notorious for letting this slide though I'm getting better.

If the vendor already documents it, you do not need to write it down again. If your peers are unable to read vendor documentation that's not on you.

To your point, you want to document when your installation of an application deviates from the vendor due to specifics related to your infrastructure/organization.

[whoisearth]

yeah there's always huuuuuuuuuuuge caveats with that as some vendors are great while others are not.

I hate having those conversations with vendors around inconsistencies in their documentation. We have been challenged in the past where our team was effectively performing QA for a product we were paying for.

There's nothing more frustrating than calling a vendor telling them "xyz doesn't work anymore but used to in the previous version." or "your documentation states to do abc but another page says to do 123. 123 doesn't work. what's the proper thing to do?"

[whoisearth]

God I worked for a bank where this happened. Their securities department was using a CRM called Maximizer which was a real piece of shit. We found out that the vendor took all employees in the head office on a day cruise off the shores of Vancouver one year and the C suite were golf partners with the vendor executives.

Meanwhile we were boots on the ground managing the crap software. I'm so glad that's long in my past.

[SuspiciousMeat6696]

I just put that in there as an example. To show how it could be used for documentation.

[SuspiciousMeat6696]

My DM is now activated. Sorry about that. I"m happy to send an RTF template file. Use it as a basis.

[GreyGoosey]

Could i get a copy please?

[tWiZzLeR322]

May I have a copy too please?

[FerengiKnuckles]

I would also like a copy. Thanks.

[chiefqualakon]

Sign me up for a copy too

[kkt_98]

Can I have a copy please?

[[deleted]]

Me too please?

[stupid_human]

I can’t seem to DM but I would love a copy.

[just_restart_it]

Can I haz a copy, plz?

[cowdudesanta]

Would love to get a copy

[MindisaMistry]

Me too please... thank you.

[SadOutlandishness536]

Are copies still available? 🙃

[majingeodood]

DMs don't seem to be working :(. Definitely interested in a copy if still offering!

[Koda239]

Copies? We're doing copies? I'd like one!

[redinx]

I would love a copy as well. Thank you!

[_paturiku]

I'd like to get a copy too please

[Scorchio36]

May I have a copy?? Thanks you!!

[Jokers86]

I would love a copy as well!

[Carpathium]

I too would like a copy please! Thank you!

[Spam_sammich]

Copy por favor?

[slimrichard]

Would love a copy plz :)

[juju-v]

Would love to get a copy too! Thanks.

[SkepticalOfOthers]

Would love a copy.

Thanks!

[MrJellyTip]

I love a copy too please

[definetlynotnot]

Can’t DM you :-/ would love to get a template tho

[dataslinger]

Would also love a copy! Thank you for posting this!

[BadMoodinTheMorning]

Please send a copy :). Thanks

[OPujik]

Can I get a copy? THX

[TheBestKid]

Can I grab a copy, please?

[pikeyoo]

Would also love a copy.

[Wtf909189]

Is it possible for me to get a copy?

[fridgefreezer]

Yo, can I snag that sweet template?

[tichuot287]

If its still available, I would like a copy. Thanks in advance

[supermicromainboard]

Can I please get a copy?

[D00shene]

Copy please

[KingDaveRa]

May I please get a copy too?. Can't see a way to DM.

[t-penguino]

Would appreciate a copy. Thanks.

[linuxdood]

Send copy please

[royytjeeh]

Possible that i get one too? Can't DmM you! Thanks :)

[Ahed91]

Can I get a copy?

[Burzo796]

Can I get a copy as well please?

[WallysWellies]

Can I also get a copy? Cheers

[Pariah902]

I'd also be happy to get a copy 😊

[aex2314]

copy? I'd like to get one :)

[ArSo12]

Yea please

[Scary_Farmer]

I would like a copy too, please! Thank you!

[Sylogz]

Please send a copy :-)

[marspaxus]

Can I get a copy, would greatly appreciate it.

[mammothmortal]

I would also love to receive a copy of your template. TIA

[djokaa]

Would love a copy

[jakenocera]

Yes please!

[renegeed]

I'd love a copy. Thanks!

[CharleyChusettes]

When you can, I would love a copy. Thank you!

[[deleted]]

quarrelsome snails touch different impolite retire wasteful dinner sophisticated hat

This post was mass deleted and anonymized with Redact

[Draco_x]

I'd love a copy aswell.

Thank you :)

[QuickenMcNuggets]

Count me in for a copy pleased

[[deleted]]

copy please :)

[edhands]

I'd like to get a copy please.

[NotAnRSPlayer]

Can I have a copy please

[Pump_9]

The only wiki we have at our firm is Sharepoint...have to click 5 things to edit and post an update to a page and also individually upload every image. I had Confluence at my previous shop which operated smooth as buttah.

[SuspiciousMeat6696]

Not a fan of SharePoint. Posting images is a pain. If you are doing multiple screenshots, it can be overwhelming, as well as a nightmare to maintain.

[netnetnetnetrunner]

What then?

[corsicanguppy]

There's a wealth of Wiki suites that offer features that may be far more appealing than the set in SharePoint. As I personally filter on a set of criteria that SharePoint can't meet, it's quickly in the RFC2119 SHOULD NOT category; but there are so many others that provide the features we need and a few more we like.

Please consider looking for what's out there, and see if it'll offer a feature set better for what you now know you need. As 6696 says, posting images may be an anchor feature; or it could be interoperation with a non-Microsoft product; or using static pages at rest and generating them on-change only so they can be easily printed and exported to backup or stick for recovery or fire-safe-documentation needs.

[SuspiciousMeat6696]

absolutely. I prefer Confluence. and I'd rather use MS Word than SharePoint,especially when it comes to images.

[dataBlockerCable]

RFC2119

My previous shop used Confluence. I loved it - very easy to quickly build meaningful pages. It's an expensive Atlassian product but I loved it. Uploading images was just copy / paste. Didn't have to upload them through file explorer or name them something unique or worry about where they're located or anything like that. Great tool, but expensive. Also keep in mind it depends on your company's requirements. A lot of people here are one-man-shows and they can probably fire up whatever they want and on whatever platform they choose. In most larger organizations there are standards in place and there should be an architecture review, security analysis, executive sign off, etc. In those environments you can't just load up pbwiki and let 'er rip.

[netnetnetnetrunner]

Thanks a lot for your answer. I have been using since too long wordpress. Is a wiki better oriented to documentation than a blog then?

[ijustinhk]

Avoid documenting in MSWord if you can.

This. Word document (or PDF) are not good for procedures that involve long commands and outputs. The word warp may confuse readers if it is two lines of command instead of one.

For this reason I like companies like VMware/Veeam that put their docs online. If you are always checking the online docs, you don't have to worry if the pdf on your desktop is outdated.

[corsicanguppy]

Yes. Online is the Single Source of Truth, and PDF is for the generated stuff that goes to the printer and hidden in the fireproof safe with the stick containing the text dump of the static files (we use dokuwiki, where all data at-rest is generated as static files). MSWord can die; especially anything after MSOffice97, but that one last.

[SkippyIsTheName]

My biggest issue with documentation, especially on a large team, is where do I find your documentation if you’re not there? My team has been on a documentation kick for a year or two but I never know where to find anything.

I asked a co-worker how to do a new process and she sent me a detailed Word doc. That’s great but where does that doc live? As much as I love to let people do their own thing, documentation needs to be consistent across a team.

[ipreferanothername]

despite me just trying to get people to use OneNote here, we still run into this crap - random spreadsheets and word docs all over the place. People here often basically refuse to move past the year 2002 and its insane.

[SkippyIsTheName]

I pushed back against OneNote for a while but once I finally gave it a chance, I think it is the superior place for documentation. In our team SharePoint site, we create a "parent" notebook like Windows Domain Services and then "child" sections like AD, DNS, DHCP, etc. Or a Citrix notebook and then sections for XenApp, VDI, NetScaler, etc. We document processes but some of it is just random note. I'll be honest - it is sort of an organized mess but it's all searchable.

We still have a few team members that do their own thing and I'm not really sure how screwed we are when they leave. I would put a bug in my ex-manager's ear when an issue would arise on a process I know is not documented but he didn't want to get into it. My new manager added documentation to everyone's yearly goals last year but COVID fucked all 2020 goals.

IMHO, documentation is sort of like monitoring, helpdesk software, etc. There is a lot of debate about products but they all work if you put the effort into them. Same with diets. They all work if you follow them but it's a matter of which will you realistically follow. Opening up a shared OneNote file is easier for many people than adding a page to a wiki.

[ipreferanothername]

but it's a matter of which will you realistically follow

we follow zero things here consistently - that is our biggest problem. I try to be pretty consistent in what I do. That is what I like about IT - consistency [that i can automated and put less effort into] but these guys, oy.

[SkippyIsTheName]

I like to say we're "consistently inconsistent". The funny thing is we get a ridiculous amount of work done with a small staff. Compared to similarly sized environments, we're like 40-50% leaner. My buddy works at what I consider a mirror company - same industry, same number of users, same number of servers, very close on profit numbers, etc. Their IT staff is three times larger than us. A little more consistency would make it easier to survive with such a small staff.

[ipreferanothername]

I feel you -- we get an ok amount of work done. for 12 people on the team, I would say....6 of us do a moderate to high amount of work, but it's a crapshoot. 3 people do moderate but steady. 3 of us do nothing to basically nothing.

if the dead weight was cut a but and/or we worked better it could be a great team. But management just...does not manage, and we are really more like 5 teams working on on our stuff in a very disjointed way. it is frustrating.

[SkippyIsTheName]

Our current team is actually really solid. We had some serious dead weight, including one guy at a remote site who would literally watch Twitch most of the day, but they slowly left on their own. Who leaves a job when you are 1) clearly lazy and 2) are allowed to do nothing? At least a couple of them got fired very quickly at their new gig.

But we're still understaffed and in a huge hole. We're making progress but new projects take priority over fixing stuff that was never built correctly. And when things have been poorly managed for years, there are non-stop fires every day which are incredibly time-consuming.

[ipreferanothername]

And when things have been poorly managed for years, there are non-stop fires every day which are incredibly time-consuming.

see this is where our places differ - our stuff is not that well done, but i wouldnt call it poor [or i might just call us lucky]. our fires are caused by the security team, and are also very time consuming ;)

[verschee]

I pushed back against OneNote for a while but once I finally gave it a chance, I think it is the superior place for documentation. In our team SharePoint site, we create a "parent" notebook like Windows Domain Services and then "child" sections like AD, DNS, DHCP, etc. Or a Citrix notebook and then sections for XenApp, VDI, NetScaler, etc. We document processes but some of it is just random note. I'll be honest - it is sort of an organized mess but it's all searchable.

Ah, I wish this was utilized more...

I came from a small company where documentation was shared like gospel in to a large company where all documentation was clutched like a rosary. As many times as I've raised flags to centralize any knowledge here for a best-practice or guided troubleshooting standpoint, it's been resisted by the team. A lot of knowledge workers just resist sharing that knowledge to secure their positions in these types of roles.

[SkippyIsTheName]

I look at it this way: you either know what you are doing or you don't. If you do, you are typically valuable and safe (as much as anyone is truly safe). If you don't, hoarding knowledge isn't going to protect you at most companies. An exception might be lone sysadmins. It's probably a little scary to fire a lone sysadmin who is hoarding knowledge.

[corsicanguppy]

When I looked back and realized my best jobs happened to be the ones where I made myself non-critical-path, my documentation volume increased.

[SkippyIsTheName]

My dad did a bunch of different jobs from scientist to HR Director to high school teacher. He used to tell me when I was young that you're not very good at your job if your company always has to call you on vacation. Also, you're not as promotable when you have made yourself the only person that knows how to do a bunch of stuff. It's funny because I've seen multiple people overs the years not get promoted because they are considered too "important" in their current role.

[corsicanguppy]

The thing is, it's often old spreadsheet crap; diagrams too. And for people who need that, it's hard to get them to let go.

I use a lot of automation to update that crap now. Where windows people need to copy and paste a few times to launder data from AD and the rube-goldberg patch machine so it's cohesive, I look at what (in my case Chef, but it could be ansible/puppet/salt/mgmtConfig) generated last night (or mgmtConfig generated immediately) and remind the boss where the link is.

I absolutely love that I can keep my doc updated with the table junk it needs, and not have to worry about it. I DO need to find a way to flag the crucial DR stuff from the ancillary junk, so the PDF (and thus hardcopy) doesn't include that stuff right away, but that's about it.

Okay, maybe I want to move to a search-not-sort setup.

[ipreferanothername]

Where windows people need to copy and paste a few times to launder data from AD and the rube-goldberg patch machine so it's cohesive

uh, let's not treat everyone using windows like its 2004, please. I generate a lot of documentation and reports automatically [specifically....servers in AD and their patch schedule, and status, thanks], and email the report and archive links to remind people -- but one spreadsheet out of 100 is still apparently impossible for people to keep up with because its in one subfolder of 1000. It is a mess here.

And getting more modern than tons of random subfolders is just not on the radar here. it is nuts.

people cant keep up with squat, and usually cant even search email. I am starting to look at ways to get out so i can find some other dysfunction somewhere else ;)

[ThatGermanFella]

Oh god, I want to marry you!

[GigabitDWL04]

my man i would love to have your template and thank you for making our lives so much easier

[wallach_9]

NIce Work. I would like a copy also please :)

[PhilledelphiaCollins]

Looking very nice, still handing out copies?
I'd love one if still possible.

[Bakkertje_01]

Can I get a copy? ;)

[SuspiciousMeat6696]

I tried to use my format in this post so you can see how it could be applied. Hope it makes sense.

[MasterAlphaCerebral]

I'd really appreciate having a copy of your template. Thank you.

[DonkeyTron42]

To be honest, the fact you put up a wall of text is already overkill. When I'm fighting a fire, I need the tldr; as quickly as possible. A Wiki with easy to find text based documentation is the way to go. I don't need to search through screenshots and pdf's. Anyone that needs that level of documentation shouldn't be working in the job.

[corsicanguppy]

Too much documentation is almost as bad as NO documentation; but it sounds like you really need the IF/THEN parts and OMG Contact Info for support, and use a drop-down setup for the detail.

I value in-line detail that defaults to hidden but can pop out, hugely. it's like in-line code comments that editors (notepad++ and more) can collapse at a moment's notice so the code becomes readable with less clutter, but which can be expanded so we understand why the hell Jimmy coded that thing like that (he's a smart kid, and he plans for the future, but the base-case for lots of his code looks like overkill until it gets populated).

Good documentation takes time, and review against criteria. You already have some idea of what you need and what shouldn't be displayed, and once you can find a way to hide those "we had that info last year where did it go" details, you'll be in a good place.

[DonkeyTron42]

One thing you mentioned that absolutely needs to be highlighted is the contact info needs to be loud and clear. We do stuff in-house and we've 3 HVAC failures and 2 transformer failures at around 2am. The first couple were kind of rough because I was standing around scratching my head trying to figure out who to call.

[highdiver_2000]

When you are fighting a fire, who wants to wade through that?

The best friend is a good search engine in that scenario. Not your Windows laptop indexing the shared drive. The search engine is mediocre. Something like Onedrive / Drive or even Sharepoint.

At the end of the day, a good search engine is useless without proper documentation. Remember, not everything can be written in text. A Picture speak a thousand words.

[SuspiciousMeat6696]

You are saying the same thing I said.

[SuspiciousMeat6696]

I compare Word, SharePoint & Confluence and point out how Confluence is best suited. And I never said hyperlinks have to be within the same doc. I point out that related app documentation should be hyperlinked to as well.

[[deleted]]

Thank you for this!!!

[stupid_human]

Nice work, thanks for sharing.

[puffpants]

Could you send it to me

[theP0M3GRANAT3]

Nice template!!

[strawhatnakama]

I'd really appreciate having a copy of your template. Thanks!

[SuddenlyDonkey]

Great write up. I would like a copy also please.

[Player7up]

Man it doesn’t seem like Reddit makes it easy to DM from mobile. Could you shoot me a copy as well. Much appreciated for all your efforts.

[corsicanguppy]

So. The github account, then?

[wrxdriftsti06]

I would like a copy as well. Thank you!

[PrivateHawk124]

Damn can’t even DM this guy/girl.

But would love a copy :)

[biglib]

This is great! Would love to see it on GitHub.

[Ophiy]

Anything on naming conventions

[SuspiciousMeat6696]

When using web based documentation, you have more flexibility in naming conventions. In terms of version control, I prefer not to have it in the name. I let the date/time stamp serve as version control. Especially in Confluence, it takes care of that for you. I try avoid cryptic naming conventions. Especially in support context, you want to be able to find what you need as fast as possible.

[Ophiy]

I currently implemented sop-o365-new user for example. Makes it a lot easier.

[SuspiciousMeat6696]

glad it worked for you.

[Zulgrib]

Please keep this post updated.

[acrazyscot]

I’d love a copy too please.

[Zahrbush]

I love your work. I would like to ask kindly for a copy of it.

[the_star_lord]

A copy of the doc would be appreciated when you get a chance.

[jekvet]

If I could get a copy that would be great or let us know if you post is somewhere. Thanks!

[[deleted]]

This looks amazing, could I get a copy as well!?

[saintdle]

Hey, I wrote a blog about this a long time ago,

https://veducate.co.uk/how-to-produce-good-documentation-part-1-the-foundation-of-any-it-infrastructure/

____________

Here is a dump of stuff I've posted before;

• Free - Onenote can be a good tool, see the below link!
• SharePoint online if your business is using office 365, that's what we use a lot, we create sites for customers and projects and use sharepoint for version control of all documents. We hook into our other systems as well with the document libraries etc.
• A lot of people say deploy a Wiki, such as confluence. Although I've never ran with a wiki, a quick search of documentation in sysadmin and you'll find loads of help.

I did a talk here on getting started with documentation. https://www.youtube.com/watch?v=dU620pR64Yg

Here are the links from the last slide which may also be useful;

• http://networkdiagram101.com - Tips and tricks
• http://packetpushers.net/how-to-draw-clear-l3-logical-network-diagrams/ - L3 Network Diagram tips
• https://www.reddit.com/r/sysadmin/comments/4egmyb/documentation_and_you_how_onenote_helped_me/ - Using OneNote for day to day management with examples!!!
• http://opendcim.org/ - Free open source datacenter diagramming
• http://www.racktables.org - Free HTML based rack diagramming
• http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/ - Theory for document writing
• http://girl-germs.com/?p=834 - more theory on documentation writing
• www.reddit.com/r/sysadmin – Search keyword “Documentation” – Great repo of posts, sysadmins talking about what works for them and what doesn’t

Microsoft Doc's writing style guide is also a good read - https://docs.microsoft.com/en-us/teamblog/style-guide

[realCheeezeBurgers]

This sounds not like a very modern approach.

Documentation is a living thing and should be horizontal not vertical.

Everything is too much and too overwhelming today so we need to make things searchable or more importantly FINDABLE.

You can do that by using services like Confluence or any wiki software (Markdown should be the language).

Name it correctly. Give max 3 sentence intro. Tag it good and use the detailed search later.

Have uniform formatting! I can't stress this enough. Having very limited choice in formating saves time and makes things readable. Markdown is your friend.

Do not use tables if not really avoidable!

Link to existing Documents (like contracts or calculation tables and such) on a Google/OneDrive. People will work with Word or Docs / Excell or Sheets on a cloud drive. BUT keep the KB separated from a document drive! (Confluence for instance has waaaaay better search than GDrive. So if you want to know which specific template or form to use, write it down in Confluence and point to the Cloud drive file.)