Want to write an Operations Guide? This tutorial explains how to write your first operations manual. It helps you get started, suggests how to format the document, create the table of contents and what else you need to include in a sample plan.
Operations Guide: Definition
What is an Operations Guide?
Definition: An Operations Guide provides instructions to System Administrators to help them manage updates, maintain computers, and run reports. It also offers troubleshooting information.
Operations Guide: How to Start
The difficulty in writing an Operations Guide, like any technical document, is to know where to start. Here’s a suggested approach:
- Who – define who will read the Operations Guide, for example, is it developers, testers or users?
- What – identify the most important tasks you need to write to help sys admins. How do you find out? Ask the people who will use it and capture their most urgent needs.
- Where – identify where it will be used. Will it be used online, printed out or read on a mobile device.
- When – is this document used in an emergency? Or is it used in less pressurized settings? How does this affect the content and the way it’s structured? When is it due for completion?
- How – create a list of who will help you write the document, provide answers, review it, and then sign off.
- Others –you’ll also need things like style guides and other supporting documents.
While this may seem a lot, focus on who will use it first and what problems you’re going to solve.
Operations Guide: Define Your Audience
Who’s going to read your Operations Guide? Before you start writing perform audience analysis.
- Identify the main user types (sys admins, testers, developers)
- Pain points
- Urgent needs
This helps structure the content. For example, if you know that developers require in depth information on how to setup a server, then provide very exact step by step instructions.
Operations Guide: Create a Format
If this is your first Operations Guide, use a template to get started.
While the template may not be perfect, it identifies the key sections for the table of contents. Once you have these in place, fill in the gaps and complete the document section by section.
Formatting the document also involves:
- Updating the cover page so it displays the version number, official document title, publication date, and possibly author.
- Updating the header and footers, for example, by including the section or chapter.
- Using a consistent font (or series of fonts) across the document. When you copy and paste from different documents, it’s easy for rogue fonts to enter the document. Use styles to control this.
Operations Guide: Provide an Outline
When the user first opens the document, provide them with an outline of what’s included in the guide. This helps orient the reader so they understand how the operations guide is structured and how information will be presented.
Here’s a sample outline:
Title: IBM WebSphere 9.0 SP3 Operations Guide
Description: This guide describes the major tasks involved in administering and troubleshooting IBM WebSphere 9.0 SP3.
In this guide you will find:
- Administering IBM WebSphere 9.0 SP3
- Troubleshooting IBM WebSphere 9.0 SP3
- Additional Resources for IBM WebSphere 9.0 SP3
- Appendix A: Uninstalling the Database
- Appendix B: Uninstalling SP3
- Appendix C: Settings for Web Services
- Appendix D: Permissions
- Appendix E: Performance
- Appendix F: Database Maintenance
- Appendix J: Setup Codes
- Administering IBM WebSphere 9.0 SP3
This section contains background information and procedures for performing the major tasks involved in administering IBM WebSphere 9.0 SP3.
In this guide:
- Overview of IBM WebSphere 9.0 SP3
- Managing IBM WebSphere 9.0 SP3
- Reports in IBM WebSphere 9.0 SP3
- Securing IBM WebSphere 9.0 SP3
Once you have outlined the high level sections, you can transition into the document, for instance:
“You can use IBM WebSphere 9.0 SP3 to manage downloading database updates from IBM and distributing them to computers in your network.”
Operations Guide: Table of Contents
Now that we have this in place, create the table of contents.
Remember that this will vary depending on your setup but the following sections apply to most Operations Manuals.
Introduce the document by describing the target audience and the systems which will be covered by the Operations Guide.
- System overview – explain how the system functions at a high level, for instance, process credit cards, record transactions, or store files.
- Authorized use – identify who is authorised to use the application, for instance developers, testers, and sys admin.
- Points of contact – identify the application owner and how this person can be contacted
- Help desk – provide details of who runs the help desk (technical support) and different levels of support, if applicable.
- Hours of operations – identify when the application is supported, eg 9-5, and when it is scheduled for maintenance, eg every quarter.
Next, provide a brief description of the operation of the system, including its purpose and uses.
- System operations
- Software inventory
- Software interfaces
- Resource inventory
- Report inventory
- System restrictions
Outline the operations team in an org chart. If useful, provide a leadership chart and identify the leadership structure within the team, such as managers, team leaders and domain experts.
It also highlights reporting relationships and reflects the management and leadership structure of the team:
- Organization chart
- Leadership chart
- Key roles & responsibilities
- Anticipated change
Here we describe how activities are scheduled. Tasks can generally be grouped into daily, weekly and monthly schedules.
Depending on the circumstances, additional administrative tasks may need to be implemented, and some tasks may occur more or less often or not at all.
- Daily tasks
- Weekly tasks
- Monthly tasks
- Backup schedule
Describe the system runs used by Operations personnel when:
- Scheduling operations
- Assigning equipment
- Managing input and output data, and
- Restart/recovery procedures
Provide detailed information on how to execute the system runs. Provide a run identifier, i.e. a unique number, to reference each run.
Finally, describe the steps required to restore operations. Describe:
- Possible failure scenarios and
- Steps to restore operations and data in that scenario
Another area to consider is update classifications. These represent a specific type of update for different products.
The following table lists samples update classifications.
- Critical updates – Fixes for problems that resolve critical errors.
- Security updates – Fixes that address security issues.
- Definition updates – Updates to definition files.
- Feature packs – New features rolled into products at the next release.
- Service packs – Sets of hotfixes, security updates, updates since product release
In this Operations Plan tutorial we’ve looked at how to identify our readers, how to format the document, and how to create the table of contents. What’s missing is how to write the Operations Plan itself. Next week, we’ll look at this.
Let me know what you think.
What questions do you have about Operations Plan? How can we help you get started?