Hello my fellow Linux people,
Could anyone help me find resources or even provide their own knowledge on creating documentation for servers in regards to maintenance and administration?
If you're looking for (good and bad) examples of technical writing check out the IBM red papers. There are also ibm white papers but i think they were a different purpose. They have alot of stuff for their enterprise servers, but anyone here is also welcome to chime in! I am curious too
1 Like
I write documentation for what I do at work all the time. Some bad some good. The old IT staff years ago when I took over left basically no documentation and what they did leave was bad, but it was something.
Some people may disagree with me on this, but I think ANY documentation even if it isn't great is better than none.
My only advice for writing is this. I write my documentation in a way that somebody with ZERO knowledge can follow them. I may be replaced or leave the company one day I have no idea the skill level of the next person, best to assume they are green. For example my instructions on how to zip up some archive data, compress it, and upload it to amazon glacier is like 30 steps long.
3 Likes
Have someone who is computer knowledgeable but has zero experience with your environment read your documentation and see what isn't clear to them. Using their input you can improve your documentation. Over time, your documentation will improve.
Things to always document:
- IP addresses / DNS names
- Credentials
- General purpose
- Pre-reboot / post-reboot instructions
- Test instructions
Other things you should document:
- How it interacts with other systems
- Support contact info (if applicable)
- Licensing info (if applicable)
Definitely forgetting some things, but this should be an OK base.
3 Likes