r/networking • u/tdhuck • 12h ago
Other Documentation - what is your 'standard' or what do you expect of documentation
This is a hypothetical I'm just looking for what you guys consider to be good documentation.
For example, let's say you are a JR network admin and you are new to the environment and the SR tells you that documentation exists for the 'routers' and 'core switches' and you can review it by typing the device hostname in the knowledge base server.
Ok, great, you do that and you see the documentation for the HA routers.
Now what, what do you expect to see?
I'm not looking for someone to copy paste their documentation, as stated, this is a hypothetical.
I see a lot about documentation on here but what does that mean? I'm sure it could mean different things to different people.
Yes, you should have login credentials for the devices documented and config backups should be automated, but lets say your backups are not good and you need to start over, are you expecting to see the full config of the routers in the documentation?
Any time I document something, I try to make it as dummy proof as I can. Maybe an accountant couldn't do anything with my documentation because they don't know what a console cable is or they don't know what SSH is, but I try to make my documentation detailed enough for a help desk tech to be able to follow the documentation step by step to resolve the issue or get it to a point where it is at least 'online' for myself or another network eng/tech/etc to be able to login and take over.
I say that because I often read documentation that was put together by someone else and aside from it being outdated, the steps are not very detailed. For example, it will say something like this.
- Log in to the server
- Get the logs
- Send the logs to support
My documentation would say something like this:
- Log into the server, the hostname is xxxxxx the ip address is xxxxx
- The name of the application on this server is xxxxxx, the logs are located in C:\Program Files\xxxxxxx\logs\filename.txt copy filename.txt that is the file that is needed for support.
- Send filename.txt to support@application-domain-name-here.com and include your case number if there is an active ticket.
Edit- My example included an 'application' and I wanted to post this in networking specifically because this is mainly a question for the networking device documentation. I wanted to make it clear that this was not incorrectly posted here instead of sysadmin, for example.