I've had discussions in the past with other people in my department about documentation, specifically, level-of-detail and requirements. In their view, documentation is a simple checklist of Y things to do when X things go wrong.
I disagree. I think that this presumes that all issues in IT can easily be boiled down to simple checklists of recovery procedures. I think that it completely ignores the complexity of the situation, and as the other people in the department don't always have a depth of understanding about the issue (which is why I'm writing the document - so they have something to refer to) that the documentation should include some basic background material, such as:
- Purpose of the (sub)system in question
- Why it is configured in that manner
- Expectations of events to occur when the settings/procedures are implemented
- Potential issues that can cause procedures to fail
However, I'm rather outvoted on this, so my documentation is required to be re-written into a form that says "Steps A-B-C applied in order will resolve problem X". I often hear the lament that it needs to fit onto a single page of paper. Try explaining the configuration of Squid ACLs to someone in this manner, including troubleshooting, through a single-page document. That's just one of a half-dozen documents that are "waiting to be written" as recovery checklists.
Is the method I'm advocating really going overboard? Or are they right, and I should just mind my business here and just write them a simple checklist? My concern is that, no matter how well you write a procedure checklist, it really doesn't solve an issue that requires a SysAdmin to think things through. If you're spending time doing a checklist of recovery procedures that ends up not resolving the issue (because there are additional factors that aren't a part of the document, due to the narrow focus of the document), and the purpose of the document was to avoid re-reading man pages and wikis and websites all over again, then why am I going through the motions? Am I just worrying too much, or is this a real issue?
There currently is no helpdesk position in the department. The audience for the documentation would be for the other admins or for the department head.