RCJC: Documents that Deliver!

Raise the Standard?

May 25th, 2015 Ron Johnson

One of the technical writers on my team found a pretty cool T-shirt online. The silkscreen on it said:

“I’m a technical writer. I solve problems you don’t know you have, in ways you can’t understand.”

Maybe that’s just a bit over the top…but it does make a point. As the client you aren’t expected to know the details of what’s wrong with your documentation. And we don’t expect you to know how to make it right. What we do hope is that you’ll recognize that our skill set can add value to one of your more valuable assets: your documents.

I’ve written about several ways that technical writers add value—writing, editing, graphics, etc.—but before any of those activities start, you need to have standards in place. How do you know if you’re doing it right, if you haven’t defined what “doing it right” means? So the step of developing standards is important, and as technical writers we need the client to “buy-in” to their importance. That’s the first step. After that the challenge is to get everyone on-board to comply with those standards.

But let’s step back for a moment and make sure we understand what we’re talking about here. The standards I’m talking about are more than just the basics rules of grammar, punctuation and format found in an off-the-shelf style guide. Style guides like the Chicago Manual of Style, the Canadian Style, or others (there are lots to choose from) are important. But I’m talking about going beyond that to develop a set of rules for your situation. For example, rules about word choices that will be understandable in your industry, on your site, and to your workers or customers.

Are your documents used by the general public? Are they in-house procedures for engineers? Are they operating manuals/procedures for plant personnel? As usual, the bottom line is always the user. Will the documents consistently “connect” with the people who will use them?

There are a lot of decisions that go into creating a set of standards for a client. We start with an analysis of the user, including who they are, what the content is about, and what the documents will be used for. We investigate what is unique about the content. Does this industry use specialized jargon? Is that jargon widely accepted? Are there good reasons to maintain local preferences, or should we try to have the user change to more widely accepted standards? Sometimes compromise (on both sides) is necessary.

As an example, take one of my recent clients—a large mining company. This mine and mill has been operating for almost fifty years and much of their operational language has evolved over that time. They like to use terminology that makes a typical technical writer cringe. For example, “Brine up the plant,” means start a series of pumps and open the correct valves to get brine flowing through multiple stages of pipes, tanks and other equipment. “Start the flakebreakers,” “Start the roll mills,” or “Start the Gundlach,” could conceivably all refer to the same piece of equipment. “Press the on button on the ABC page of the Foxboro screen,” is understandable to operators who have worked there for years, but it breaks most of the conventional style rules (according to the Microsoft Manual of Style).

Sometimes brand names become synonymous with a process or type of equipment. “Start the Bird,” refers to a common brand of centrifuge, except “Bird” was bought out a few years ago by another company that no longer uses that name. In documentation do we continue using the common term (Bird), change to the new manufacturer’s name (Andritz), or use the generic term? And how difficult will it be to convince personnel to make that change?

Given the task of updating and creating new documentation, the technical writer has to navigate the delicate path of establishing new standards, and then get the client to cooperate. This can be challenging. Often, this can involve changing years of ingrained habits. We’re back to the idea of “buy-in”.

When a client makes the decision to upgrade, or create new documents, and they see the need for expert help with the task, they have to also decide whether to accept a re-evaluation of their standards. Experienced technical writers will work with their clients to develop a set of standards that will strengthen their documentation. That might involve some adaptation (maybe even some inconvenience and discomfort), but the change will make their documents more consistent, which will decrease the chance of ambiguity. Ultimately, that will result in better productivity, quality and safety. Isn’t that what we all want?

 

Sphere: Related Content

Read More »

Revisiting the SOP Toolkit

May 20th, 2015 Ron Johnson

A wise old philosopher by the name of Heraclitus once said “The only constant is change”.  If Heraclitus recognized that in 500 BC, how much truer is it today? Especially in our world of high technology, industry and competition. Change IS constant, and we all have to ride the wave, adapting and re-tooling while in motion. To be competitive, to be safe, and to be responsible we have to evolve new processes.

All this is driving us to deliver more services at ever more demanding levels of quality and accountability, while contending with limited budgets and an aging and increasingly mobile workforce. We are constantly looking for ways to remove inconsistencies and risk from our operations and processes. One of the solutions is to capture and retain the knowledge, skills and best practices, and use them to standardize and train personnel to a high level of consistency.

Standard operating procedures, or SOPs, are a key tool in these efforts. Progressive organizations see the value of standardizing work processes, but they don’t always have the in-house expertise needed to create quality documentation. Nor do they have expertise in managing documentation processes. Moreover, most organizations have not factored in the staffing resources needed for developing documentation.

A while back I put some excerpts on this site from The SOP Toolkit, an ebook that I wrote a few years ago. I’ve decided to take that a step further and make the entire book available as a free download – no cost and no strings attached. The book shows you how to successfully set up and execute a process to design, develop and create a library of standard operating procedures. It includes information on how to analyze what you need, develop your own documentation plan, and acquire the tools to create clear, usable and standardized procedure documents.

The ebook includes what an SOP is, what its purpose is, what should be included, and how it should be used. I share the practical lessons I have learned from developing SOPs, manuals and learning materials for a variety of clients in the water and wastewater, mining, manufacturing and educational fields. I also show how to examine your own situation and evaluate your documentation needs. I review a variety of types of SOPs, the difference between content and format, and the need for consistency, standardization, and document plans. The SOP Toolkit also examines the SOP development process–how to assess needs, plan the project, and implement other steps critical to successful completion of the SOP.

The SOP Toolkit actually contains much more than I’ve described here. Click here for a table of contents.

So the question is: “Why am I making the SOP Toolkit ebook available free on my website?” There is no great mystery to it. I’m hoping when you see what is involved in creating great procedure documents you’ll be interested in contracting with my company to get yours done.

I realize that you may get everything you need from the book and do the job yourself. But I’ll take a chance on that, because I think once you see what is involved you will see the value in getting an expert to help. I believe you know value when you see it, and will want the best outcome you can get.

So take a look at the table of contents here, or just go ahead and download The SOP Toolkit here.

And after you read through the SOP Toolkit ebook, I’d ask you to seriously consider dropping me an email (ron@roncjohnson.net) or calling me (306 229-9842). I’d love to talk to you about how we can create or update your procedures to get them to the level you want and need.

Ron Johnson A.Sc.T.

P.S. I also have fully developed, tested, and tried workshops based on the ebook. I can provide a 3-hour introduction to the concepts, or a one-day hands-on, interactive workshop. Both of these will help your personnel develop skills that will maximize the effectiveness of your SOP development process, whether you contact with a technical writer (me, I hope) or not.

Sphere: Related Content

Read More »

Ten Things Technical Writers Wish Their Clients Knew about Technical Writing

May 7th, 2015 Ron Johnson

As you might expect, technical writing is not just about writing. Certainly writing is a core skill, but depending on the job, the industry, and the purpose of the writing, a technical writer may wear many hats. Often tech writers’ responsibilities touch on editing, graphics, photography, formatting, marketing, training, designing, and document management/control, just to name a few.

That said, my experience has been that clients typically don’t understand what a technical writer does, why they do it, or how they go about accomplishing their tasks. As a result, clients have trouble accepting the value proposition being offered. That often leads to tech writing services and work product being under-valued, overlooked and under-maintained.

I make these comments with all respect. It isn’t the client’s responsibility to know technical writing. But there are a few things that technical writers wish their clients understood about technical writing. Here are a few of them…

  1. Tech writers focus on the user.

Everything is rooted in serving the user of the documentation, which means that the user must be identified and their needs assessed. We need a target to shoot at and it’s important to not include too wide a range of users for a particular document.

  1. Tech writers (usually) aren’t SMEs.

Every technical writer tries to develop a basic understanding of the content, but usually they won’t be at the level of their subject matter experts. Clients need to understand this, and make sure the technical writer gets the support needed to do their job.

  1. Tech writers are more than typists.

Recognize the skills that the TW brings to the table. We may not understand the content at the SME’s level, but we understand what is necessary to organize and present information effectively.

  1. Tech writers aren’t engineers.

Tech writers often work with engineers. In fact, some of them are engineers. But the tech writer’s job is different, and technical writing is not the same as the type of writing that most engineers learn to produce in college and on the job. Accept that your TW is going to tweak the language, de-capitalize some of those “important” words, and generally make changes that enhance communication with the user.

  1. Tech writers don’t make these rules up.

The styles, formats and principles applied by TWs may seem “picky” and arbitrary, but they are based on widely accepted standards. And yes, every organization and industry has a few variations. Tech writers evaluate which ones are acceptable for clear communication, capture them, and create in-house style guides to ensure consistency within the organization.

  1. Tech writers don’t write fiction.

Well, maybe some do, but the point is we can’t make this stuff up. We need good, consistent, timely support from the client’s SMEs. If a document doesn’t get finished it may be waiting for content that hasn’t arrived.

  1. Tech writers CAN compromise. (They just don’t like to.)

Technical writing requires consistency and attention to detail. We like to establish the rules and stick to them. But there are situations where unique vocabulary, specific work processes, company culture and history dictate some latitude in the application of standards. Ultimately it is about ensuring clear communication.

  1. Tech writers save you money (if you let them).

Good documentation is an investment, not an expense. Studies have shown that investment in quality documentation pays off in significant savings, less product support, efficient operations, and better safety and environmental records.

  1. Tech writers build quality into an organization.

Organizations that create quality documentation enhance the quality of the organization. Workers understand the expectations that are on them. Supervisors have resources to help them train and develop their workforce. Managers can rest assured that procedures, process and training resources are in place.

  1. Tech writers extend value when they maintain your documentation.

Documents are one of your organization’s assets. Company assets require maintenance. Time and money spent on creating documentation is wasted if the work product is not regularly maintained. Expect to support your investment with regular maintenance in order to keep it providing the value it was originally designed to provide.

Sphere: Related Content

Read More »

Lessons Learned on the VAULT Project – Part 2

March 27th, 2015 Ron Johnson

In Lessons Learned on the VAULT Project – Part 1 I mentioned how important project management skills were to successful completion of our most recent project. For those who may not have read that post, our part of the VAULT Project spanned almost three years and required the creation of several thousand pages of procedures, checklists and training materials in support of a large capacity expansion of a local potash mine and mill. My team, including several technical writers, an administrative assistant and a training coordinator, worked with a large number of SMEs to accomplish the task.

As I mentioned, project management was a big part of the project, and I learned some valuable lessons about project management in the process. A couple of key lessons included the importance of team building and how to break down barriers to communication and buy-in.

I’m calling those lessons: Tweaking the Team and Over (or Around, or Through) the Hedge

Tweaking the Team

Most of my technical writing contracts to this point have ranged in size from small to medium. Usually I have been able to handle them on my own, or with the assistance of two or three sub-contractors and interaction with a similar number of subject matter experts (SME). This project required the focused efforts of several writers, an admin, a training coordinator and a large number of SMEs. The team started small but grew over several months. That process included several rounds of interviews with job applicants, reviewing resumes and then selecting the successful candidate. As each writer joined the team, I spent time bringing them up to speed on a process that was ongoing, and evolving. It was important to identify each team member’s strengths and work them into a role that matched their abilities. Just as important was building a sense of team and ensuring everyone felt part of the process.

Certainly there were false starts, uncertainties in the process, and a lot of adjustments along the way. Occasionally, I found myself in a writer’s office saying, “Remember what I asked you to do yesterday? We need to do that again, but differently.” I also remember team meetings where I marveled at the accumulated talent and how much we were learning from each other.

Looking back on the process my assessment is that we found a niche for each of our team members. Each was able to make unique, valuable contribution to the effort. We all contributed to the the writing, but one writer also became our key graphics person; another brought a wealth of training development expertise; still others shone in the areas of prescriptive language, style guide creation, and standardization. Our administrative assistant became our expert on checklist standards and managed that process with precision.

The lesson learned? Everyone brings something to the table. Build on their strengths; be open to change. The effective project manager finds ways to bring them together in an effective team that covers all that is needed. As Aristotle said: “The whole is greater than the sum of its parts.”

Over (or Around, or Through) the Hedge

Every workplace has its own culture. Specialized industries also tend to evolve unique vocabulary, spelling conventions and documentation styles. These can be difficult to change. We found that the existing library of legacy documents was large, but standardization was lacking. Styles and formats varied drastically depending on the era and the personnel who created the documents. There was very little in the way of documented standards. Our challenge was to introduce new standards that were based on proven technical communications theory, meet the specific needs of the client, and as much as possible, integrate with the existing library. We needed to do all this, and not alienate the users.

Early on we also became aware of what we began to call The Hedge, a “porous barrier” to communication between the our group and the operating company – the people who would be using the documents when the project was complete. Our group was part of the effort to expand the facilities; theirs was to continue operating the existing facility until the new systems were complete. We had different priorities and points of focus. We also had somewhat different organizational cultures. Often they were quite content with the status quo; we needed to make some changes.

Information did filter through The Hedge, but rather slowly. Getting buy-in on our new formats and standards was a challenge. We found it was quite possible to create content and “toss it over The Hedge” but this wasn’t always the most effective approach in getting buy-in.

Developing good communications and effective cooperation took time and effort. We reached out by inviting stakeholders to meetings, joining internal user groups, actively participating in joint events, and seeking out one-on-one interaction wherever possible. We asked questions and listened to the answers; compromised where necessary; educated whenever possible. Eventually our perseverance paid off and we began to get some traction. As we developed productive working relationships with key personnel The Hedge began to come down, thin out and, in some areas, disappear.

Ultimately the key to both of these challenges was in developing relationships. Relationships are integral to teams and to communication. They take time and effort to build. In this project we learned investing that time and effort in building relationships paid off. For me, those are the key lessons learned.

Sphere: Related Content

Read More »

Lessons Learned on the VAULT Project – Part 1

March 11th, 2015 Ron Johnson

With our part of Agrium’s VAULT project coming to an end some reflection on lessons learned from the experience is in order. Without a doubt this project has been the largest my company has undertaken. Over the last two and half years, with the help of a team of four technical writers, a training coordinator, an administrative assistant, and dozens of subject matter experts, we have created several thousand pages of content. That content has included procedures, checklists, learning modules, presentations and evaluation materials. (To give credit where credit is due, another company created some of the presentation materials, which we then updated to our standards and incorporated into the mix.)

What have we learned? Where do I start?

Probably one of the most significant challenges on this project has been project management. Every project I have led requires some project management expertise, but the magnitude and breadth of this one stood out. Despite the volume of documents to be created, the arc of design, research, creation, verification/validation, publication and release had to be compressed into approximately two years. When the project started very little had been predetermined about what was needed. Early on documents were already being created while the document formats and standards were still in flux. This caused more rework later than we would have preferred as changing formats and standards forced us to update earlier versions. The main lesson we learned from the exercise was that it would have been better to start the process several months to a year earlier. Unfortunately this was beyond our control.

Once document creation was underway the challenge of keeping track of the progress of several hundred documents–all in different stages of completion and verification–was a real challenge. Very quickly we had to develop a number of systems and processes. Early on we created a document that outlined the steps involved in developing, reviewing, verifying and validating each document. The document also defined the people (and groups of people) who were part of the process, and responsible for finalizing each document. A clear definition of the process–which started out to be quite onerous and time consuming–was critical, but we soon found ways to streamline it to improve efficiency. Once the process was clearly defined it became clear that to implement it we needed a way of keeping track of the status of each document and a tool to allow us to access that information at any time.

No doubt there are a number of tools available to assist with this type of task. Since the customer already had SharePoint available, and inhouse expertise available to support it, the decision to set up a document library to manage documents was easy to make. We created one large library with many views that allowed us to sort documents in categories such as Owner, Tech Writer, Last Modified, Document Category, Type, Name and Number, Status, etc. We added some sophistication by creating a large number of different views based on a variety of sorts. This allowed us to quickly access collections of documents and display specific fields of information for each. In addition to status fields, we added comments fields where each writer could add short comments each time the document was worked on.

As we worked our way further into the document creation phase it became clear that a large number of personnel needed access to the library. I soon had four TWs and an administrative assistant within my group. In addition we were working with a training coordinator, an external contractor and a team of subject matter experts that hovered in the neighbourhood of a dozen or so. At least 20 other people wanted access to the documents for reference and other purposes. To make it possible for them to easily locate the documents on their own we created a wiki with a homepage that featured a matrix of links to library views.

The wiki–set up in SharePoint–also served as an easy way to document our processes, resources and an in-house style guide for the project.

(More on our wiki, the development and verification processes, and lessons learned in our next installment…)

Sphere: Related Content

Read More »
« Older Entries
Newer Entries »