I have spent most of my professional life in information technology (IT) doing various technical support roles and technical writing. One thing I learned is that documentation is critical and therefore technical writers are necessary. The sad reality is that many companies think that technical writing is a luxury or something that can be done in someone’s spare time. The misplaced assumption that technical writing is not real work. The fact of the matter is that good documentation solves problems, saves time and money, and will reduce technical support calls.
During my IT career I became interested in how to combine my technical skills with my passion for technical writing to produce better documentation, processes, and procedures. I observed many teams repeatedly squander resources on redundant problems because no one wanted to take the time to document solutions. My initial question when I incur a problem is where is the documentation? The common answer was that there was no documentation or you had to ask a certain person because they fixed it last time. Those were not acceptable answers so for the past 23 years I have taken on the task to document solutions. The good news is that the documentation benefitted my teams which proves that IT teams need a technical writer.
The following scenarios are real-world examples where I used my ability as a technical writer to improve processes and procedures, and save companies time and money.
So Easy We Don’t Need Documentation
I worked for a large insurance company where my job was to train insurance agents to use our applications so they could submit policies. The company released a new application and my first question was where is the documentation? The response was that the application was so easy to use that documentation was not necessary. The reality was that the insurance agents did not use the new application and policies were being submitted to other insurance companies.
My solution was to spend a couple days in my office and document the application. I used Microsoft Word and included screenshots and brief explanations to create user guides that explained how to install the application, process a quote, write a new policy, and submit the policy. I used these documents as a training tool and distributed the documentation to my clients. The agents began to use the application and submitted more business and I spent much less time on the phone doing technical support. An added benefit was that the entire Western Region began to distribute the documentation and we had better trained agents.
Search Prior Tickets
During my career there were countless occasions where a new product or feature was launched with no advance notice to the technical support team. When problems arose, the typical workaround was to search through prior tickets and hope that someone had already solved the problem. If you did find a prior ticket there was no guarantee that whomever worked on the problem took the time to document the solution. More often than not, the typical ticket closing note was Done or Resolved.
This presented another documentation opportunity. When I worked in technical support I documented my tickets with the problem that was reported, my troubleshooting steps, and the resolution. Because complex problems spanned several iterations of troubleshooting, software patches, reboots, and other tasks I would write a summary of the problem and the steps that resolved the problem. That was useful information for the next time someone searched tickets to find an answer and for escalations to engineers. I then used the ticket information to create wiki pages that my team could bookmark for future reference.
Process? What Process?
Many IT departments think they have solid processes or they begin a project to implement process management but do not follow through to completion. And, like a good golf swing, follow through is critical. Hardware management is often overlooked, but it is important. For example, the ability to track hard drives that were ordered, installed, and failed is important for data security. Inventory management for replacement parts that are required, ordered, or received is necessary information when a team is responsible for server repairs.
Companies fail to address hardware management and the team that is responsible for server repairs wastes hours looking for parts, submitting redundant orders, or failing to resolve hardware problems. As a technical writer with an interest in process management I fixed broken processes and procedures. I worked with management and convinced them of the need to document a solution. I developed the processes and procedures, tested and iterated the documentation, created a basic website to track hardware orders, and published the documentation. The result was a more efficient hardware management process that saved time and money.
I worked in hardware engineering and my responsibility was to receive server hardware from manufacturers and test it against the design specifications and customer requirements. A common problem was that that when the hardware arrived it was unusable in our environment. To get the hardware to a usable state it was a cumbersome, time consuming series of emails and phone calls with the vendor’s engineers.
My solution was to write a specification that explained what was expected of the hardware. This was a one-page document that explained the necessary components and firmware to connect the server to the test environment. I wrote a Linux shell script template so that the vendor could install the required firmware before the hardware was shipped to our lab. This solved the problem and we began to receive hardware that we could connect to our test environment and begin our tests.
When I was tasked to do the onsite vendor audits and verify server manufacturing processes, I asked where is the documentation? The documentation did not exist because one person had done all the prior audits. The problem was that there were a number of tasks that needed to be completed: travel, specification reviews with engineers, hardware tests, hardware configuration review, and compile the data into a management report. The typical audit was a one-day event so it was necessary to have a documented process to capture the necessary information.
I wrote the vendor audit process that included the steps for the initial contact with the vendor, travel planning, how to perform the required onsite tasks, management report, and travel expense report. For the hardware tests and hardware configuration reviews I created technical documentation that described the procedure for the hardware tests and developed Linux scripts that automated the capture of the hardware configuration. The result was an efficient process that guided anyone on the team to a successful vendor audit.
All of these examples prove how a technical writer was able to analyze problems and develop documented solutions that saved the company time and money. The documentation enabled other people on the teams to perform tasks and find useful troubleshooting information to solve problems. Words are work and it takes time for a technical writer to create useful documentation that is written for the audience. This is the value a technical writer brings to a company.