How do you keep documentation from becoming outdated a few months down the line?
Posted by PersonalTrash1779@reddit | sysadmin | View on Reddit | 18 comments
We usually start with clean docs (diagrams, access info, notes), but over time things drift IP changes, new devices, config tweaks and eventually people stop trusting the docs.
Currently looking at a few approaches: - NetBox for inventory/source of truth - simplifying and reducing what we document - possibly tools like DeepDocs to catch when docs fall out of sync with real changes
For those managing real environments, what actually held up over time without constant manual effort?
totallynotcrabppl@reddit
For us, if you don't have a task in your change to update doco and CMDB your change isn't getting approved
skcortex@reddit
I was also practicing this approach đ and number of code reviews I was assigned to do slowly dropped. Now when Iâm talking to external devs - api consumers, I have to apologize for inconstancies. We all know it (is one of the problems) during the sprint planning phase, yet nobody actually plans these âsubtasksâ.
SevaraB@reddit
Thatâs a people problem. Enforcing that methodology has to come from the top down. It shouldnât just be that your PR doesnât get approved, it should be that you donât get to push again until youâre back in line.
SevaraB@reddit
Static configs will eventually become a problem. Same with static docs. Jinja templates and scripts are cheap- use them to your advantage and youâll never have to worry about the data being up to date because it will always be updated without you having to remember.
Nyohn@reddit
I mean, shit, even Lotus Notes had a function for notifications on document-reviews at set intervals. What software are ya'll using that lacks this?
OneSeaworthiness7768@reddit
Mods removed your last post about this. So which one are you advertising/doing market research for?
InspectorGadget76@reddit
By asking MS to stop rearranging the location of settings in M365 and Azure etc every week.
admlshake@reddit
Copilot will take care of all that for you! Not how you want, and not a way you would like, and you'll probably have to redo all of it, but for a low low monthly price just let copilot do it!
ArticleGlad9497@reddit
Why is the location of settings in your documentation in the 1st place?
If it's the odd screenshot then fine but in my experience people like to spoon-feed every click to people and all it does is promote a team of "IT" engineers who can't think of work things out for themselves.
bridge1999@reddit
The super detailed documentation is for when the on call person gets hit up at 2 AM and canât think straight
fdeyso@reddit
AAND stop fckin swapping coulomns of csv exports from the same location every couple of monthsâŚ
tristand666@reddit
Updating the doc is part of the job. If you are changing things and not updating the documentation, you are failing at your job.Â
unJust-Newspapers@reddit
Repeat after me: Unless pulled directly from a device with a script, Netbox is not the source of truth
If you can change the information without changing the configuration, you have a pane of glass, not a source of truth.
VioletiOT@reddit
Domotz can really help automate this for you! We will automatically detect new devices and also provide monitoring via MAC address so devices will not constantly appear as new. A lot of IT users like plugging that information to their documentation tool to keep it updates. We're over on r/domotz if any questions. Free trial details here!
BisonThunderclap@reddit
MSP guy here. We deal with multiple environments, so it's a nightmare when it's not up to date.
I've found creating recurring tickets that generate for review to be the best way, and it should be part of your documentation process.
Say you're deploying a new enterprise application. You have to document user onboarding/off boarding/configurations/error setup ect.
When you're done with that, a recurring ticket for that application should be made. Set it to generate as you'd expect the document to need to be updated with the longest time out being an annual review.
Within the ticket you should state that the tech that grabs this needs to verify each document for this application still works or update it.
While this may be low priority work at the moment, attach a bounty or reward to working these tickets. Attaching PTO in increments of half an hour a piece per ticket really made these popular to work.
MGMan-01@reddit
This is part of the change management process for any professional organization.
Sudden_Leadership800@reddit
It's never out of date if it doesn't exist
But depending on what it is - infrastructure diagrams etc can be automated, config changes should be in config management etc so unless you're being extremely specific or don't have a change management process?
Borgquite@reddit
Discipline.