Short of hiring or outsourcing to a Tech Writer, are there basic standards/conventions/practices that Technical Writers employ in their trade that can be learned from in order to create proper IT documentation and maintain that documentation over time?
While writing various documentation for both internal IT usage and external use by our employees, it has become clear that our employees all have their own style when it comes to the documentation.
Pulling from our Quality documents and controlled documentation, IT has utilized various templates for SOPs, WI's, and various forms used for IT quality docs. These docs, while not necessarily that useful for day to day operations within IT do help employees and the company with IT HR issues, compliance, etc. and are typically well written, well defined, and follow at least the Quality dept.'s templates and documentation standards (like versioning, ECNs, etc.)
But our actual IT document writing is still lacking a true convention/standard. Some will use 3rd party tools like ScreenSteps, others simply use Word and create a simple outline like:
- Click on `Start Global Thermonuclear War"
Internal IT documentation is actually worse, based on whatever the employee or consultant felt was sufficient at the time to either jog their own memories or was based in their editor of choice (vi, word, excel, powerpoint, napkin, internal wiki). The problem comes when an employee leaves or is on vacation and a scramble is made to figure out even basic information. At times only the file date is an indicator of whether the data is still relevant or not.
While a simple outline, actual screenshots, or even full on HD video are all well and good, we don't have an actual IT Technical writer on staff and can't help but think we are lacking in this area.
Could we make up our own standards for our documentation along with approved templates? Yes, but why re-invent the wheel? If such standards and conventions already exist within the Technical Writer's "guild" we would be better served to follow those conventions so that our documentation is clear, concise, and professional.
To avoid being told "Google It", I did look at sites that showed some formatting practices and while this SF Q: IT Documentation Platforms helps with finding platforms and software to handle the writing, it doesn't discuss if there truly are standards within the industry.
So, short of hiring or outsourcing to a Tech Writer, are there basic standards/conventions/practices that Technical Writers employ in their trade that can be learned from in order to create proper IT documentation and maintain that documentation over time?