Skip to main content

Sample 1: Process document

💼 Project title​

Runbook creation process for existing business services

📂 Context​

In my previous role as a Technical Writer, I proposed a new process for the client's IT department. I also created an accompanying document describing how to execute the process from start to end.

For my first writing sample, I decided to write a high-level process document loosely inspired by that project. This document is neither meant to be detailed nor demonstrate an in-depth understanding of ITSM (IT Service Management) or ITIL (IT Infrastructure Library) best practices. Instead, I've created it to provide an insight into my writing abilities. I tried to keep it short and straightforward.

I wrote a process document for Pentagon Health, a fictional healthcare company in the Philippines. The company has several operational business services but no documentation explaining how the IT teams and operators run them. Pentagon Health's IT managers hired Technical Writers to fill in the gap.

To jumpstart the documentation process, a Senior Technical Writer is tasked to draft a process document detailing how to create a business service runbook. It establishes a standard operating procedure for preparing the runbook and will serve as a reference for other Technical Writers.

👥 Target audience​

The target audience of this process document is Pentagon Health's current and future Technical Writers. It serves as their onboarding guide for creating a process runbook for existing business services.

The document also orients other IT teams on their involvement in the runbook creation process, especially the help, materials, and deliverables they need to provide.

📝 Runbook creation process for existing business services​

Introduction​

The purpose of this document is to provide an overview of the runbook creation process for Pentagon Health's existing business services.

As a Technical Writer for Pentagon Health's Information Technology (IT) department:

  • You will own the runbook creation process for a specific business service.
  • You are responsible for the planning stage up until the approval stage.
  • You are accountable for the content development process.
  • You will set timelines and deadlines for every step, which will be monitored and approved by your Team Lead.

Some of Pentagon Health's existing business services already have available documentation, while others do not. You will either have to gather additional information or help build the data from scratch.

To do this, you must collaborate with the Application Owner, Business Analyst, Software Developer(s), Subject Matter Experts (SMEs), and other internal teams. You will also work with them to verify the runbook's clarity, consistency, accuracy, accessibility, and usability.

Before you begin​

Assumptions​

This process document has the following assumptions:

  • You are familiar with Pentagon Health's organizational structure and IT operations.
  • You have a working knowledge of IT Service Management (ITSM) and IT Infrastructure Library (ITIL).
  • You have a general understanding of Pentagon Health's business services, including what they are and what they do.
  • You know what a business service runbook is and what it does, especially in the context of Pentagon Health's business goals and IT operations. You must be familiar with the technical terms used in the runbook template.
  • The team assigned to a business service consists of an Application Owner, a Business Analyst, and Software Developers.
  • Technical Writers are only responsible for the planning stage up until the approval stage, which is the scope of this document. Once approved, the assigned Technical Writer will hand over the runbook to the Release Manager for deployment.
  • Once deployed, the Application Owner is in charge of updating and maintaining the business service runbook.

Before this assignment, make sure you have already finished and understood Pentagon Health's Onboarding Guide for New Employees. When in doubt, approach your Team Lead.

Limitations​

This process document has the following limitations:

  • The process document only applies to existing business services. In other words, it does not apply to business services currently under development or in the planning stage. There is a separate runbook creation process for new business services.
  • The process document only covers the planning stage until the approval stage. The succeeding stages–the deployment and maintenance stages–are outlined in other process documents. The deployment and maintenance of the runbook will be the responsibilities of the Release Manager and the Application Owner, respectively.

About this task​

Runbooks are reference documents describing how to operate Pentagon Health's business services. They include technical specifications, operational procedures, checklists, disaster recovery plans, and other related documents and reference materials.

Runbooks are created for one of the following reasons:

  • Experienced operators document their daily tasks and share their knowledge in runbooks. It ensures that their know-how is not merely stored in their brains but can be shared between all operators and passed on to future team members.
  • Runbooks serve as an onboarding guide for new operators or team members who will be assigned to a specific business service.
  • Runbooks eliminate the need for memorizing multiple steps and complex processes. Operators only need to consult the runbook if they need to perform a task, resulting in an efficient and successful implementation.

Procedure​

Step 1: Set a meeting with the team​

Pentagon Health's existing business services are assigned to a specific team, typically consisting of an Application Owner, a Business Analyst, and Software Developers. Other business services may require more specialists, but these individuals are the core team members. They run, monitor, and update the business service and will be your key contact persons during the runbook creation process.

  1. Know the names and contact information of the team members in charge of the business service.
  2. Reach out to the team via email.
    2.1 In your message, briefly introduce yourself and your new assignment.
    2.2 Schedule an initial discovery call or meeting with the team so you can learn more about the business service.
  3. During the meeting, be proactive in taking notes and asking questions. Remember, you must have a better understanding of the business service after the discussion.
  4. Ask the team if the business service has documentation, such as user guides, operations manuals, system reference manuals, service level agreements, and many more. Request a copy of these documents and any other reference materials related to the business service.
Notes
  • The initial discovery meeting aims to give you working knowledge of the business service. The team may provide a process or application walkthrough, presentation, or seminar to achieve this objective.
  • If possible, try to learn as much as you can about the business service before the meeting. However, this is not always applicable since some business services do not have online information.
  • Prepare some questions before the meeting.
  • You can also record the session if you prefer. Do not forget to ask for permission beforehand.

Step 2: Review the available documents​

During this step, you will review:

  • The documents that the team provided,
  • The Business Service Runbook Template, and
  • The Business Service Runbook Creation Tracker.

You must update the tracker as you review the available documents. For more information, refer to Appendix A: Business Service Runbook Creation Tracker.

  1. Gather and organize all the documentation and reference materials you have obtained.
  2. Review the documents, the latest versions of the business service runbook template, and the runbook creation tracker. Update the tracker as you go along.
  3. Note any questions or clarifications you may have.
  4. After reviewing the documents, contact the team to shed light on your questions and concerns.
Tips
  • To keep things organized, create a main folder to store all documents.
  • You can create a simple spreadsheet to keep track of the files. Feel free to devise a system that works for you.

Step 3: Gather information​

The information-gathering stage ensures that you have all the documents and information you need to write the first draft of the runbook.

  1. Contact the SMEs assigned to specific runbook sections. The Enterprise Architect, for example, should be able to provide the necessary information on the business service's System Architecture.
  2. Schedule discovery meetings with the SMEs to obtain or build the necessary information.
  3. Continue scheduling meetings with the SMEs until you have the necessary information.
Notes
  • The goal of this stage is to have adequate information on all sections of the runbook.
  • For some sections, the SMEs may take longer to supply the information, especially if it has to be built from scratch. Sometimes, you may have to proceed to the next step even though you still do not have all the data on hand. Rely on your best judgment for this step.

Step 4: Write​

Now that you have obtained all the necessary information, you are ready to write the first draft of the business service runbook.

  1. Add the information to the appropriate sections of the runbook.
  2. Research as needed to craft a narrative and piece all the information together into a cohesive whole.
Notes
  • The information from the SMEs may come in the form of diagrams, images, incomplete write-ups, summaries, presentations, and so on. Your responsibility is to fill in the gaps, provide contexts and explanations, and make everything accessible and easily understandable for your target audience.
  • During the writing stage, you may need to consult the team or the SMEs to clarify certain information or confirm your understanding.
  • When in doubt, do not hesitate to ask questions. Doing this early on can help you down the road.

Step 5: First review​

The runbook is ready for initial review after writing the first draft. Specifically, the assigned team and the SMEs need to review the runbook draft for clarity, consistency, and accuracy.

  1. Send the first draft to the team and the SMEs.
  2. Give them a deadline to go over the document.
  3. They should return the document with their comments and feedback.
Notes
  • It is highly recommended to schedule a meeting with the team and the SMEs so they can discuss their feedback and the changes you need to incorporate.
  • Having all the involved individuals in one meeting will allow them to ask questions to each other. The Application Owner, Business Analyst, and Software Developers, for example, can state their concerns to the SMEs and vice versa.
  • If there is a lot of ground to cover, you may need to schedule a series of meetings.
  • As always, take notes. Record the sessions if necessary.

Step 6: Revise and edit​

During this stage, you should revise and edit the first draft of the runbook based on the feedback and comments you received.

Step 7: Second review​

After revising and editing, the assigned team and the SMEs must review the second draft.

  1. Send the second draft to the team and the SMEs.
  2. Give them a deadline to go over the document.
    2.1 If they are satisfied with the document, you can proceed to Step 8: Test.
    2.2 If not, they should return the document with their comments and feedback.
  3. Repeat the previous step until they are satisfied with your output.

Step 8: Test​

Once the draft is approved, it is time for the operators to test the runbook's clarity, accessibility, and usability.

  1. Send a copy of the runbook to the operators.
  2. Give them a deadline to test the runbook.
  3. Once the operators are done testing the runbook, schedule a call or meeting with them.
  4. During the meeting, ask for their input and overall experience using the runbook.
    4.1 If the operators are satisfied with the runbook, you can proceed to Step 9: Approve.
    4.2 If not, proceed to the following step.
  5. If the operators are unsatisfied or you think you can still update the draft, revise and edit the runbook draft based on the feedback and meeting discussions.
  6. Repeat the previous step until the runbook draft is deemed clear, accessible, and usable.
Notes
  • An effective business service runbook should allow the operators to carry out various procedures smoothly. The steps should be clear and easy to follow. The runbook should also contain all the additional information they need to perform their tasks.
  • The Application Owner or the Business Analyst should be able to provide you with the names you need.
  • Take notes during the meeting.

Step 9: Approve​

Once the runbook passes the test, it is time to accomplish the sign-off sheet in sequential order.

After you—the Technical Writer—have signed, the Software Developer, Business Analyst, and Application Owner must follow suit. If any of them remain unsatisfied with the runbook, you will have to revise the document until you secure their approval.

Next steps​

Once the sign-off sheet has been accomplished, you have completed your assignment. The business service runbook will now be officially handed over to the Release Manager, who is in charge of the deployment stage.

After the runbook has been cascaded to the IT department, the responsibility for updating and maintaining the business service runbook falls to the Application Owner. The team may request writing, editing, and formatting support from you now and then.

Appendix​

Appendix A: Business Service Runbook Creation Tracker​

The Runbook Creation Tracker is a spreadsheet designed to help you monitor the progress of the runbook creation process. It can be found on the IT team’s Confluence page.

The tracker contains four columns:

  1. Runbook Sections
  2. Assigned Subject Matter Experts
  3. Available Information
  4. Notes

Refer to Figure 1 for a sample of the spreadsheet.

Runbook creation tracker screenshot

Figure 1 – A screenshot of the Business Service Runbook Creation Tracker on Confluence

Tip

Right-click on the photo and select Open Image in New Tab to enlarge it.

Refer to Table 1 for a brief description of each column.

Column TitleDescription
1.Runbook SectionsThe first column enumerates all the sections in the business service runbook.
2.Assigned Subject Matter ExpertsThe second column lists the SMEs assigned to a particular section and their respective roles and contact information.
The Configuration Management section, for example, is assigned to the Configuration Manager.
3.Available InformationThe third column is a place to note if you already have adequate information to write a particular section. You need to indicate Yes, Partial, or None.
"Yes" means that you have enough information for that section.
"Partial" means that some information is available, but you still need to research and consult the assigned SME.
"None" means there is no information available for that section, and the data needs to be built from scratch.
4.NotesThe fourth column is a space for you to add your comments. For example, if there is partial documentation, indicate which information is available and the document's name.

Table 1 – A table explaining the fields in the Business Service Runbook Creation Tracker