Collaborating with Casual Authors
In this article, I show that the key to collaborating with casual authors does not lie in pressuring them, but rather on lowering “the wall.”
While a technical writer (or content developer) lives and thrives in a constrained and controlled environment (style guides, terminology, taxonomy, and so on), casual authors are not centered on creating content and complying with company standards. They have other work environments, other tasks, and to make it plain, other concerns.
We will first look into casual author profiles and environments, suggest strategies to enhance collaboration, and then present one real-life use case.
Collaboration Flash Poll Results
I conducted four flash-polls, while preparing my presentation for the CIDM CMS/DITA North America 2013 conference, from April 10 to May 17, 2013. I submitted the same poll on four LinkedIn groups: Documentation and Technical Writing Management (37 votes), STC (29 votes), The Content Wrangler (17 votes), and STC France (8 votes).
Ninety professionals responded, and the poll was strongly commented. As presented in Figure 1, Poor process (26 percent) and Unclear information plan/structure (27 percent) have the highest and nearly same score, followed by Lack of communication channels (19 percent). Inadequate tools (10 percent) ranks the lowest in the result.
There are a few unofficial takeaways from the results. There is not one, but multiple pain points. The Other (18 percent) results prompted 65 comments that can be split into four main categories:
- Lack of leadership and control
- Lack of management commitment
- Lack of participants’ commitment (time, circle-writing, interest)
- Missing coherent writing style
One participant commented “On dealing with non-technical authors, or, in fact, any author whose principle job is not writing, you want to use structured writing techniques as much as possible, because you want to structure the information they provide you in order to get some measure of consistency and completeness.”
New Industries & Team Environments
One of the promises of the DITA standard is automation, reduced content volume, and enhanced consistency throughout the information in the organization. Cheri Mullins, content strategist at AMD, explained at the 2012 Best Practices conference, “DITA benefits for writing projects are a focus on content—Get out of the formatting business, enforced consistency, and ease of data interchange.”
As DITA grows out of the software and hardware industries and into new ones, new cases and organization models emerge.
In some industries, the information is chiefly developed by people who are not professional writers, with one lone writer-cum-editor dealing with what’s put in front of her. In these settings, the technical writer is the “lightest” side and must bow to how and what information is provided by the experts.
Leading a project in such an environment therefore requires careful planning, minimalist workflows, and tools to collect best-quality information (structured, compliant to your style guide and business rules, categorized, and so on).
As one person pointed out in the poll comments “There is no good way for four people to play the same piano at the same time. There are lots of good ways for a quartet to play together on separate instruments.”
So, in keeping with Figure 2, let us form a strategy that can
- help communicators effectively implement collaboration with casual authors, that is, non-professional writers or communicators.
- help communicators consider constraints for selecting tools and frameworks for their teams.
- provide tips to drive success in DITA projects.
Profiling Casual Authors
First, we must understand who we are working with and who contributes information. Yes, you know them. However, all projects are different and becoming familiar with creating personas for casual authors helps. The personas are not the real casual authors, but personify, in one profile, the common constraints and characteristics of a “group” of authors.
Remember, the casual author
- has a primary job—he or she can be a support engineer, a subject specialist, a researcher, a trainer, and so on.
- has a distinct work environment—in a different organization, in a different country, in a lab, at sea, in the desert, or (less exotic) in a car.
- uses different language, colloquialisms, jargon, and so on.
- uses different tools—to write, to connect to the organization, to communicate.
- uses different devices—PC, tablet, print, and so on.
- responds to other tasks and processes—his or her main job task!
- has his or her own experience with writing/editing and probably has “bad” habits.
To create your personas, you must collect information from the casual authors. You can do this with questionnaires, phone calls, or face-to-face meetings (See Figure 3).
From the answers you should have at least a good idea of
- the best time to contact a group of casual authors
- the best tools to provide them
- the kind of deadline you can set
- what communication channels they favor
- the tool’s constraints (device, accessibility to network, and so on)
Enabling Casual Writing—Creating the Right Framework and Tools
The main instrument to engage with casual authors is communication. This view is strongly supported by the community. It is very important that you bring a common definition of the objectives, expected results, and the meaning of deadlines to the team.
Make sure to provide a shared repository or site where the team can share templates, syntax examples, guidelines, resources, and training. Provide communication channels so the authors can share advice and tips. When such channels are open, the main author should answer questions, curate the content, and provide what’s necessary (including praise) so the other authors can complete their assignments (See Figure 4).
The team should be aware of the big picture and understand the information architecture. Even when working on smaller parts of a project, the casual authors should understand what they are contributing to and who the other people involved in the project are.
If they understand the importance of their contribution, authors are more willing to know the other team members, can relate to each other, seek guidance, build a feeling of collaboration, and even enable unofficial peer reviews.
Usually, one or two people emerge as champions for the project. You should groom these champions as they can provide peer support to the team, project endorsement, and facilitate project or tool adoption. One way to support them is to provide them with more training and further insight and to ask their advice.
Shared Repository, CMS, and Editors
You should build a DITA XML repository with the adequate support for the distributed team.
Check that the shared repository is available to all, either outside the firewall, on an app, or accessible with a different device (iPad for example).
Most authors will access the repository. You should define what the role of each casual author is and what rights they should be granted. An easy way is to provide modification rights only to the information needed for the task.
Of course, the shared repository is a good place to provide the communication channels, training, examples, templates, and project planning, reducing the number of tools needed for your collaborative project.
Selecting the right editing tool is imperative. An online tool is appropriate when the casual authors are distributed in different organizations. It enables collaborative writing and reviewing, should be adequate for the devices and operating systems of each casual author’s work environment, and always be available in the right time zones.
Adapting the Information Model
Your casual authors have a primary job and tasks. Time is essential. You should expect only the information required from the casual authors (See Figure 5).
With the casual author in mind, consider the following questions:
- What is the added-value information provided by the casual author?
- How much metadata do you require them to add? Which metadata would help them?
- How much of DITA do you expect them to know?
- What is the lowest content quality you can accept? Alternatively, how much should a technical writer edit the content?
You should capture the best quality content with the lowest effort from both the casual authors and the technical writers. That’s when designing templates becomes necessary.
Use form-based writing when the content is highly structured, as in collecting data on field reports. If this is not possible, you should use precise templates, enriched with as much metadata and information as possible so the casual authors do not waste time. You can tailor the templates for the specific project and add more comments and examples to guide the casual authors. Of course, as the casual authors get more familiar with the project writing guidelines, you can update the templates and provide extra training.
You may also simplify the casual authors’ work by automating classification, providing quick access to template topics, making sure reviewing with track changes is available and easy, or further adapting or specializing DITA.
Recognize the work done by the casual authors, acknowledge mishaps, evaluate and correct the content, and provide feedback. Open the discussion with the casual authors—different views may be eye-opening!
Streamlining Collaboration with Minimalist Workflows
If you are using workflows, make sure these are perfectly tailored for your audience. In the case of casual authors, every click and action counts, and you should remove every pointless action.
(Re)designing the workflows with swimlanes, per profile, provides an excellent view of what exactly is requested from your team. Make sure to use adapted workflows for each case: writing, peer reviewing, validating, and so on.
Advantage of a Single Format and Online Service
Casual authors and the professional writing team need to use the same tool to eliminate manual information rework and risk of human error—not to mention time lost during reformatting, exporting/importing, and re-sending the information.
An online writing environment ensures that the contributors can connect whenever they want to with a 24/7 connection service; the single repository allows reuse at the block and topic level. The organization then moves from multiple desktop editors, to a single repository and single architecture, thus allowing multiple users to connect and update or review content on different pieces of information simultaneously.
Engaging with More Writers in the Organization
Earlier time-to-market, better content quality, more willing (and less harassed) writers are all signs of a more successful project (see Figure 6).
These few tips regarding personas, tools, framework, and template design should help you decide where to put your efforts when starting a collaborative project with casual authors.
We touched on the importance of considering the casual author as we would a customer: by adapting our usual requirements to their possibilities. As is often the case, in areas where information is mainly expert-sourced, the technical writer is responsible for the information quality with no real control on its development. Migrating to structured content, such as DITA, provides an opportunity to create a better collaborative environment and more successful outcomes.
Collaboration Use Case: Standards Body
One of Componize’s new customers is a standards body, with specialists developing most of the content.
When the standards body contacted Componize, it was quite clear that structured content was necessary. Advanced control on workflows and workgroups was also key to a beneficial system with strong collaboration features.
This short use case presents the project requirements and Componize’s response.
Stakeholders and Workgroups Organization
Each standard is developed and maintained by a dedicated workgroup and reviewed and signed off by stakeholders. These collaborators are subject matter experts, not technical writers. The writing team cannot really expect them to learn about a specific XML architecture so the writing tool must mask the tags and be easy to understand and use. These experts must view their own content but may need to see the entire standard for contextualization at the writing phase, but also for review and validation purposes.
The DITA CMS should offer an easy way to add and group users and provide them with access to the right information.
Constraints of a Dispersed Team
The workgroup experts are dispersed geographically but also work for different entities. They have specific work environments and use different platforms, connections, security and policy constraints devices, writing environments with different tools, but also different versions of the same tool, and different proprietary output formats.
Before migrating to structured content and Componize, the writing team from the standards body had to rework and recompile the content manually in the appropriate form and resend the information whenever an aggregation or allotment was needed for stakeholders or reviewers.
With Componize and the embedded authoring tool, the workgroups can use the same writing and math notation tools, quickly preview, and upload images in context or in an online media library (See Figure 7).
Workflows for Writing, Reviewing, and Validating
The content of each standard follows a strict structure and must go through two validation processes, two reviewing and commenting phases, and one editing phase prior to publishing and dissemination. The workflows therefore must provide good audit trails and be easy to use.
Componize provides these workflows and customization ability to further extend the powerful workflow engine for faster deliveries.
Easier Administration of Workgroups and Stakeholders
Each standard is developed as a separate project, with contributors sometimes working in one or more workgroups. The organization therefore needs a tool to map the authors and the access they have to different standards.
For this, Componize offers a flexible way to quickly add and map users to workgroups, subgroups, and projects.
In short, switching to structured content and Componize enabled the standards body to
- present all authors with the same writing tools for editing text, reusing content, writing equations, and previewing images
- easily create workgroups of users, providing a single space for content, an activity dashboard, and specific workflows
- provide quick access for reviewers, 24/7, with no local installation or device constraints
The standards body hopes that the new technology and methods will speed standards development and encourage more experts to participate in the process of standards development.
About the Author:
Nolwenn Kerzreho is presales consultant for Componize Software, the company editing the same-named DITA-focused content management system.
Prior to Componize, Nolwenn was an information developer, information architect, and trainer, and led the DITA adoption effort at Technicolor Broadcast & Multimedia, a technology leader in digital and video services.
Nolwenn is also an adjunct teacher at University of Rennes 2, focusing on user-oriented documentation, international standards, and XML-based writing, and promotes technical writing in France through professional organizations.
You can contact Nolwenn at firstname.lastname@example.org or follow her on twitter @nkerzreho.
Dr. Alan Cooper
The Inmates Are Running the Asylum: Why High-Tech Products Drive Us Crazy and How to Restore the Sanity
2004, Indianapolis, IN
Dr. JoAnn Hackos
Information Development: Managing Your Documentation Projects, Portfolio, and People
2006, Indianapolis, IN
Collaboration at Citrix
John P. Walsh
Collaboration Structure, Communication Media, and Problems in Scientific Work Teams
Using DITA XML for Standards: A Manifesto
March 11, 2013
Chapbooks of Harrow, Kindle Edition