It All Starts with Standards
“Standards.” The very word brings a chill to the creative bones of the technical writer, while simultaneously creating a warm fuzzy in the heart of the project editor. As for the managers of technical publications departments, visions of dollar signs dance in their heads: will the immediate cost of creating and implementing such standards balance the long term savings in translation, reuse, and updates?
Although the best practices of highly efficient information development groups clearly indicate a need for standards, the trick is in knowing what to include and how to obtain buy-in. This article provides suggestions for how to get started defining your standards.
Beyond the simple fact that having standards is a best practice for the most effective information development groups, other factors might have more of an impact on the decision to create and maintain standards:
- Growth in your department has brought in new people who need orientation to how things are done in your organization.
- Your company is looking to outsource content development and your vendors need governance.
- Acquisitions by the company are bringing new documentation and training departments with differing or conflicting ways of doing things. You need to merge the best approaches into one unifying standard.
- Product lines that share similar, if not the same, audiences require similar approaches to avoid confusing your customers.
- Digitization of the information assets of the company offers the potential of significant re-use of content in a variety of media to a variety of audiences, if that content fits together well.
- Needs for translation mandate a more efficient process and an economy of words.
While the reasons forhaving standards garner no argument, the extent of what to include in those standards proffer more debates. Before you can begin defining standards, you need to agree on what you mean by the term:
- Are standards simply a style guide, dictating writing style, word choice, and acronyms? Are you going to reinvent the wheel of The Chicago Manual of Style?
- Who is your audience? Do you need to cover the basics of each profession, or can you assume that your audience already knows how to write, draw, program, and so on?
- Should standards define the work process as well as the work output?
Your answers obviously dictate the content required. The following sections suggest chapters to include in your style guide depending on your goals. Before you begin creating your standards guide, consider these chapters and create a content plan by selecting the ones that make sense for your organization.
Although it seems rather basic, you might need to start with a solid definition of your various information product types. Too often, companies call similar products by dissimilar names, while customer expectations of what those products contain are based on the name. For example, the word “textbook” calls up one mental image, while “manual” and “handbook” meant different things. Yet all of these terms might be slapped onto similar products. Product standards address this issue and others:
- What is the difference between a demo, a tutorial, e-learning, and Computer Based Training (CBT)?
- What sections must always be included in a user guide? An installation guide? A technical support guide?
- What is the purpose of release notes?
- What distinguishes a study guide from a test guide?
- Who are the intended audiences for each end product?
- What are the printing specifications (page size, paper weight, binding, color) for each type of product?
- Do products require different formatting templates? Are they developed with different tools?
While you might think that job responsibilities should be handled by human resources, not a style guide, HR job descriptions do not always match how specific job positions are actually used by their project teams. You might find it necessary to include responsibilities, accountabilities, and authorities of team members into your standards to answer these questions:
- Who has the last say if team members disagree? For example, if a subject matter expert disagrees with a project edit?
- What is the difference between a project editor, technical editor, and a copy editor?
- What can a team member do if the work given to them does not meet the expectations of the entrance requirements? For example, what can an editor do if a document was clearly not spellchecked before being submitted?
- Who is in charge of screen captures, the writer or the graphic artist?
- Who can make changes to the template?
- Who can grant an exemption to the standards?
Although the simple availability or unavailability of tools sometimes provides a default standard of what you can use, if you have multiple tools available, you might want to use your standards document to answer questions such as:
- What file formats are appropriate for graphics, audio, and video?
- What programs and versions can be used to create computer-based training?
- When do you use FrameMaker instead of Quark?
- What is the preferred XML editor?
- What software is required to maintain historical products?
- How is the decision made for upgrading to a new software version?
- What is the migration plan for moving from one tool to another?
It only takes one or two times for a manager to hear “I updated the wrong file,” or “My computer crashed and I lost all my work” to realize the need to standardize and enforce good file management practices, including:
- What source control system will be enforced?
- How frequently do files need to be checked in?
- How often are back-ups created from user computers? From the servers?
- When do you archive files from the active directories?
- What file naming conventions shall be used?
- What standard directory folders should be created for each new project?
At one level, it seems work flow should naturally be the same in information development—you write something, it’s edited, it’s published. But the devil is in the details, and far too often process differs depending on the project manager, the product type, or even the whims of the day. Inconsistent development processes add confusion as staff members move between projects and make it difficult to track project progress. Although you must remain flexible enough to adapt to customer and time pressure demands or to crisis situations, consider standardizing such issues as:
- In what order do technical, project, and copy edits occur?
- What is the process for rejecting an edit?
- How many review cycles will there be (internal and external)?
- What must be delivered for a first draft review (i.e., graphics or only graphic requests)?
- When can programming begin—before or after media production?
- Do you always require a hand-off between one phase and another? Can you hand-off deliverables in pieces, or does one phase need to be completed before the next can begin?
Embedded in the workflow is the question of how that workflow will be managed and tracked. Standards and artifacts recommended by the Project Management Institute (PMI) or the rational unified process (RUP) might seem like overkill for some documentation projects while too limiting on others. For example, recommendations to limit task size to minimums of 8 hours makes scheduling some documentation tasks which are less than this impossible, while at the same time keeping tasks to maximums of 80 hours can be similarly restrictive for large chapters or lessons. Set project management guidelines that work for the types of projects your team develops:
- What project management artifacts are required for a project?
- What size tasks will you track (duration and/ or work effort)?
- How often must status reports be provided and to whom?
- How are risks and issues documented and mitigated?
- How is the project team kept apprised of project issues?
- What is the process for time reporting and validation?
- What information is included in a typical project management plan?
In practice, you don’t want to reinvent the fine job that the University of Chicago has done in writing and publishing The Chicago Manual of Style. But neither do your team members want to look through the thousands of pages in that guide for a simple answer. You need to balance carefully what content should be included in your company standards with what can be well referenced. Your standards must cover things that your organization might do differently than is typical. Consider covering such things as:
- What acronyms are acceptable without spelling them out?
- What terminology is preferred?
- When might you use the passive voice?
- Do you use a serial comma?
- What capitalization scheme do you use in headings?
- What is our preferred narrative form?
- Are there different styles for software documentation vs. training?
- What is the difference between writing for web content and writing for print?
- What information is included in a typical content plan?
In addition to answering these types of questions, you should also list your preferred references for covering issues not explicitly in your standards, such as:
- Merriam-Webster’s Collegiate Dictionary, 11th edition
- The Chicago Manual of Style, 16th edition
- Microsoft Manual of Style for Technical Publications, 3rd edition
Graphic Design and Photography
Especially as graphics and photos become reused in different media, with different resolutions and different sizes, standards became painfully necessary to ensure the best quality everywhere. Sample topics include:
- What color palettes are acceptable?
- What file formats will be used?
- What are the procedures to follow when capturing screens?
- How do you obtain and manage permissions to use graphics from other sources?
- Will you resize graphics at the source or in the application in which they are embedded?
- What resolution will you store images at?
- When is it acceptable to included text in an image?
- What metadata is required to help locate an appropriate image?
Although audio and video work might represent only a small fraction of the work you presently do, they still need standards—perhaps even more so than the written word for it is in these areas that you will be compared to mainstream entertainment. To maintain an acceptable level of quality, you need to define:
- How is professional talent selected?
- What file formats will be used?
- What is the maximum length of a media clip that will be used in a CBT?
- What is the minimum window size in which you will display a movie?
- Are audio clips embedded within a Flash animation or called from outside?
- What is the appropriate frame rate for your source and your output?
Formatting (style sheet) Standards
Formatting standards typically document the style sheet(s) you are using. They describe things like:
- What are the page margins?
- What fonts and sizes are used for each element?
- What is the leading between paragraphs?
- What type of bullets are used and how much should the list be indented?
- How many paragraph levels are included in the table of contents?
- How does information flow around figures?
- How are figures, tables, and pages numbered (sequentially, folio by chapter)?
- What information goes in the header and footer?
In developing training, you might encounter strong lines between learning theories and approaches; for example, do you subscribe to behaviorism or constructivism, or do you even know the difference? To avoid long philosophical debates, your instructional design standards should specify:
- What instructional design model will you follow?
- What are the required parts of a well formed behavioral objective?
- What verb list will you allow for objectives?
- What question types are appropriate for what levels of objectives?
- How many questions should be written for each objective?
- What type of feedback will you provide?
- What information is included in a typical training plan?
Beyond the basics of how learning is designed, you might also need to define standards for the management of that learning. If you are in charge of training, your standards should include learning management strategies for assigning and tracking learning, including:
- What data must be collected for student records?
- Will you conform to any e-learning standards, such as SCORM or AICC?
- How will students register or be assigned to courses?
- What reports do instructors need about their students?
- How long will students have access to completed content?
- How long are student records kept in the system?
- Will students require printed completion certificates?
- What reports do instructional designers need for question validation?
If you are involved in e-learning of any kind, you also need to develop standards for the interface of that e-learning. Without standards, e-learning can become quite expensive as each individual screen becomes its own work of art. Standards define:
- What navigation elements must be present?
- What screen types are available?
- What question types are available?
- When do you use audio?
- What are your linking strategies—within the training? to locations outside the training?
In a typical project, testing windows always seem to be shrunk as other phases of development expand. The standards in this category help to protect that function from non-existence as they define what must be included in testing. In addition to functional testing, this section can also cover usability testing standards and should include issues such as
- How do you report a bug or issue, and how is the status reported back?
- How many test subjects are appropriate for a beta test of a CBT?
- What information should be included in a test plan?
- What’s the difference between usability and functional testing?
- What are the definitions for each possible severity level?
- How are priorities assigned to reported issues?
Standards help set the groundwork for a move to re-use strategies which typically include structured, topic-based architectures. As you move to these strategies, your standards will need to expand to define:
- At what level will you reuse information?
- What structural rules must your documents conform to?
- What Document Type Definitions (DTDs) and XML schema will you adopt for which situations?
- What metadata do you need to define and capture?
A successful standards definition project needs to be treated as a real project, of equal priority as any other work you are doing. Without this status, most standards projects fall to the wayside, pushed aside for more “important” things. Establish a budget for the creation of the standards, allocate dedicated resources to the project, and set a schedule of deliverables that has to be met. Making standards a priority also sends a message to your team that you are serious about standards and helps to set the stage for compliance when the standards are finished. The following sections discuss key strategies in the development of standards.
To obtain an appropriate amount of funding for your standards project, you need to build a business case around the needs and benefits that started this article: re-use factors, productivity factors, and translation factors. These benefits need to be weighed against the cost of creating, maintaining, and adopting the standards:
- Obviously the cost of development depends on the number of sections you have determined you need to include. Plan for a minimum of one month for each section to allow time for research, writing, and reviews.
- Needs change over time, and your standards are no exception. Once your standards are developed, be sure to allow time in all subsequent years for regular evaluation and updatin. Roughly 10% of the original development time should be adequate, but track the actual efforts in the first few years to ensure you have allowed enough time.
- Not only is there a significant cost in the creation and maintenance of the standards themselves, but the cost of conforming to those standards can also be prohibitive. How many existing products do not conform to the standards you are creating, and what will you do about that? Consider initially grandfathering in all existing product lines with an understanding that the next time those products are updated, the budget will include the costs of updating them to conform to your new standards.
It’s a well-known fact that many people think their specific projects are unique and that standards are a great idea for everyone else but them. When standards are forced upon these people, they can dig in their heels and slow down adoption. To overcome these attitudes and get as much buy-in as possible, staff your standards development project with the people that you identify would be the biggest resistors if they weren’t involved. This strategy makes them invested in the standards they create, and instead of making the biggest noise against them, they are influential in their acceptance.
In addition, don’t adopt any standards without a comment period, where the drafted standards are available to the community for comment. This assessment period gives your staff the opportunity to be heard and to feel they are part of the process.
- Assign a primary expert to take charge of each chapter in the standards document.
- The assigned expert meets with others in the department, researches industry best practices, and drafts the recommended standards.
The expert also creates checklists to accompany the standards where appropriate and creates templates wherever possible to eliminate interpretation issues.
- The drafts of the standards are reviewed by the entire standards team; that is, the experts in every area.
- An approved draft of the standards is distributed to the community for comment and validation.
- After the review period, the standards are officially adopted and rollout begins.
As with any big change, communication is the key to a successful introduction of the standards. Throughout development, keep all staff members informed about the project, ask them to participate in various discipline meetings, and give them opportunities to comment on draft standards.
After initial roll-out, be sure also to plan for continued notifications regarding the standards. Establish how you will communicate changes and exceptions to the standards; for example:
- Will staff receive email notifications of changes?
- Will there be updates made to an intranet or wiki site?
- Will changes be highlighted in the documents for a certain period of time?
- Will special training be held to roll-out changes?
In addition, another critical factor is actually training the standards. Although everyone is able to read the standards, reading and understanding are not the same thing. Do not provide opportunity for your staff to plead ignorance about the standards. Schedule multiple training sessions:
- In the first session, introduce the standards to everyone, reviewing in detail conformance expectations and change management and exemption processes, and providing a high-level overview of the contents of the individual standards.
- After the initial level-setting, schedule individual training sessions on each of the topics in detail. Require people who are affected by that topic to attend, leaving the sessions open to any others who would like to come.
- Consider scheduling yearly refreshers on the standards or asking the editors to create periodic training that highlights the most common standards that are being overlooked.
- Establish a community of practice not only to support each other in the use of the standards but to periodically review industry trends for improvements that might be made to the standards.
Like any document, usability is a key factor in the acceptance of the document. A thorough standards document might be hundreds of pages of reference material. Your team must be able to easily locate and understand the information in the standards to use them effectively. For best results, your standards should be online, well-indexed, and searchable. Install shortcuts to the standards on your staff’s desktops, and link to them on your intranet site. However, discourage downloading to individual machines so that you can be sure the most current standards are always being referenced.
Ultimately, a significant factor in acceptance and buy-in is the accountability factor. If team members are not held accountable to conform to standards, they won’t. The standards will become just another thing that that editors check for and correct. To establish accountability:
- Update job descriptions to state that every person is responsible for conforming to our standards, and therefore non-conformance is a performance issue directly impacting reviews and raises.
- Give editors authority to return drafts that do not conform to the writer for clean-up before editing begins.
- Allow for random, spot-check verification by supervisors.
- If possible, adopt a tool that can report the number of standards issues in documents at specific phases of development, and include acceptable levels and goals in individual performance appraisals.
The reasons that standards can so often rankle is the fear that all factors may not have been considered. Certainly it’s impossible to think of everything the first time out. In addition, there always seems to be a special case—customer-driven requirements for a specific product may go against the standards established. Absolutely critical to the acceptance of your standards is an acknowledgment of these facts, a provision for exemptions, and a change management process.
In fact, you should standardize your exemption and change management process. Establish a Change Control Board, likely composed of the experts who wrote the standards In the first place, that can convene to grant exemptions, adopt new standards, or change existing ones.
Enable teams with customer requirements, or even just a desire to have a project-specific style guide that bends or breaks the standards, to request an exemption from the standards. These requests should be evaluated by the standards Change Control Board, for both the immediate question of granting an exemption and the long-term evaluation of whether the exemption should also drive a change in the standards themselves.
In addition to exemptions, allow anyone to submit a proposed change or a new standard at any time. Convene the Change Control Board on a regular basis to review these submissions and implement those that have merit.
Return on Investment
Although defining and implementing standards demands significant time and energy upfront, the presence of standards directly translates into tangible benefits for your group:
- Standards point everyone in the same direction. If training and documentation is to be a core competency within the company, you cannot dilute it by letting people go every which way. Standards keep everyone focused on the goal.
- Standards bring new people up to speed faster. Not only do they provide the initial orientation a new writer or editor needs on the way you do things, they also ensure that help is available for those new people wherever they turn—anyone can answer their questions and you can be sure the answers will be the same.
- Standards help control costs by improving efficiency, eliminating questions and arguments, and preventing trips down a rabbit hole. Creative endeavors frequently are difficult to measure as they are somewhat subjective. While a writer might argue that “utilize” is a perfectly valid word, if the standards say don’t use it, the argument is no longer a matter of preference and taste. Projects with standards leave less room for interpretation and provide a clear process to follow throughout development, making them easier to manage.
- Standards provide an unbiased way to hold writers and editors accountable. Although you still need to measure productivity, you can set measurable objectives surrounding the adherence to standards.
- Standards free editors to concentrate on the larger issues, rather than copyedit problems. If all writers are expected to adhere to standards, editors need not spend most of their time bringing the document into compliance but can look more at structural, readability, and usability issues. In addition, some tools enable you to automate checking for standards compliance, so that writers can validate their work against standards before they even send the document to editing.
- Finally, in a backwards benefit, standards provide unity to the team by providing a “common enemy”—edits are no longer personal but can be blamed on the standards instead.
In an environment of acquisitions, where users change jobs frequently, as the globe gets smaller and the demands for translation increase, and the need continually increases to find more economical ways to provide information products, you can scarcely afford not to turn your attention to standardization. Reusability, translation memory, and automated editing tools—they all start with and rely on standards.
Comtech Services, Inc.
Dawn Stevens is a Senior Consultant at Comtech Services. She worked at Comtech Services for 10 years before leaving to work for Boeing. After 10 years experience at Boeing, she has recently returned to Comtech to continue her consulting role here. Dawn works with clients to help them improve their publication processes through process maturity studies, user studies, information architecture, minimalism and topic oriented writing using XML and DITA.