Select Page

In our previous blog, Looking at Trends in Technical Content Collaboration, we examined at some of the results of our annual State of Collaboration survey. As promised, we’re following up today with a deeper dive as we explore ways that organizations can work together to improve the timeliness, relevance and quality of their technical content.

One of the most interesting aspects of the survey were the ideas for improvement that respondents shared in the comments section.  Here are some we heard most often:

1. Implement a system for enabling collaboration

Last time we summed up the top item on most people’s documentation wishlist this way: “A single, online system for managing content from authoring to approval.“ Breaking that sentence down into its parts we can examine the benefits of such a system:

  • single source system of record makes it easier to manage quality. Information only has to be maintained in one place, and version control ensures that everyone is working on the most current content.
  • An online system enables collaboration by granting easy access to content to a wide range of contributors. The best systems will also create a shared space where the team can communicate with each other and coordinate their activities.
  • Workflow tools speed the authoring, review, and approval process and encourage participation by making the process quick and painless. Good reporting capabilities help managers see at a glance where the bottlenecks are.

If you have a DITA CMS already, is it fully functional? While most CMS systems give knowledge managers workflow tools for review, the survey found that most people are working without automated audit trail capabilities or any way to easily track metrics around collaboration.

CMS capabilities chart

2. Use customer feedback to drive change.

One of the great advantages of putting your product information online is that you can measure how it is being used (or not used). What content are people actually viewing? How well (or poorly) are they navigating through the information? A respondent from the education industry told us what she needed was “a smooth, useful method for tracking content use and feedback from the end users.”

Page view numbers alone can be revealing. For product documentation teams, just seeing what subjects are popular can help identify additional content to prioritize. trackpopularityFor a product engineering team, “popular” might not be such a positive thing. When a page gets a lot of hits, it can indicate that something about the product is causing a lot of problems or a procedure is not as intuitive as it should be.

The next step is to enable feedback from end users. The simplest forms of feedback are thumbs up/thumbs down or sliding scale rating systems. They can help you ratingsdistinguish the good kind of popular from the bad. More advanced systems allow users to comment on what they read or even contribute content themselves.

A technical writer in the software industry wants “better feedback from product support about what problems customers have, so I can determine the information that customers really need. useratingsOften, by the time I get to hear about an issue, it’s been filtered through someone else’s view of the solution.” With the easyDITA CMS hooked up to the Mindtouch online help system, you can collect unfiltered user feedback right in the authoring environment.

When you are building a portal, an information architect at a well-known CRM provider suggests that you make it “easier to mine for data related to documentation. The problem is that customers may mention a problem they are having but if they don’t flag it as related to documentation the feedback will never find its way to the right team.”

3. Promote information as a key company asset.

A product evangelist told us what he really wants is “better discussion between the documentation, development, support, and product teams to enable pre-sales and sales.” We couldn’t have said it better ourselves (though we tried, in our DITA for Everyone white paper.) The fact is, everyone has a stake in creating Great Customer Experiences (hey, that’s the name of another white paper we did.) When you reach customers with relevant information when they need it the most, you increase brand loyalty and make more sales.

Organizations are healthier and live longer when information is flowing across the enterprise, especially among the customer-facing departments. As we said previously, creating a shared collaboration space can be one of the great benefits of online information systems.


A tech pubs manager told us that she wants more interaction with the product team and SMEs, but “we work remotely in different countries, so the logistics of this can be difficult.” She goes on to say that “a CCMS (component content management system) would be of great help, but we are on a very low budget.”

Using a free solution like Google Drive can get you started collaborating online. It offers many advantages to discussing issues in long email chains and collecting review comments on marked up PDFs or hard copy. It’s not going to really help you get your content into DITA, though. For that, you’ll have to copy and paste from Google into an authoring tool.

If you have a small budget, consider easyDITA, which does not limit the number of reviewers who can access and comment on your documentation.

4. Get agile with your documentation.

It says a lot about our sample pool of respondents that over half said they were working in an agile environment. Agile development methods have traditionally been associated with the software industry, but they areagile chart increasingly being adopted by high tech manufacturing and other industries that reward the rapid development and deployment of new and improved products.

The agile development process forces organizations to rethink their documentation practices. Here are some aspects of agile that can have a good effect when adopted by technical writing teams:

  • Base documentation on user requirements – Just as software developers begin by asking, “what do users want to do?”, tech writers can use the customer feedback loops we talked about earlier to ensure you prioritize the most useful content.
  • Collaborate inside cross-functional teams – Agile makes collaboration the standard operating procedure. Yeah! Want to know how DITA can help get a good back-and-forth going between tech writers and code writers? easyDITA’s Casey Jordan wrote a blog about that.
  • Create iterative and incremental documentation – Let your documentation set evolve instead of starting with a rigid, preconceived Table of Contents. Short, focused DITA topics are well-suited for writing documentation “on the fly”.

Chris Despopoulos is a tech pubs manager in the software industry. He told us he wants to “Add review capabilities to the interim builds. Our process encourages incremental ‘growth’ of the documentation as the project evolves. Each daily build includes the latest doc changes. It would be nice to have a doc display that includes fields for SMEs to add comments on the fly to the docs.”

Note to Chris: easyDITA enables SMEs to attach their comments directly to each DITA topic. 🙂

We employ agile development methods at easyDITA, and we write our documentation that way too. We blogged about it here.  As we ramp up for a major new release of the software later this year, we will be posting more insights about our “documentation first” approach to information development and how it intersects with our code writing.

5. Find a strategy to deal with people problems

Not every problem can be easily addressed by technology. Some are people problems. A technical writer / information architect in High Tech Manufacturing says her wish is for “more time to spend together with collaborators.” No technology can put more hours in the day, but it can make collaboration quicker and more convenient, fostering “communication between those that know and those that don’t,” as a tech writer in Life Sciences industry succinctly put it.

Collaborating with “those that know”, aka SMEs, is clearly one of the major headaches of the tech docs department. Some appear to have lost patience with gentle persuasion and have moved on to coercion!

  • “Make sure technical documentation support is a part of SMEs job description.”
  • “Hire a program manager to keep all departments in line.”
  • “Make people responsible for their part.”
  • “Make it mandatory.”
  • “Mass firings of all the stubborn people!”

In addition to getting more people involved in content creation and review, there is a need to improve the quality of what is being produced. “The great benefits of topic-based, structured writing can only be reaped if the content is developed with structured-writing principles in mind,” said a tech pubs manager in the Semiconductor industry. “All too many of our content contributors still believe that they can just slap words and pictures on a page like they used to, and still expect them to work in a content-reuse environment. Then they get frustrated when it doesn’t…”

A content strategist suggested that managers “have people assigned to the roles that best use their talents and skills – and then it would come naturally” – which might be a good long-term strategy but wouldn’t lessen the pain right away. The fact is that structured writing is new to many people, and everyone could learn how to do it better by reading a book or taking a seminar.

TechWhirl has a lot of information on their brand new DITA portal, including links to upcoming training events, conferences, and other resources. Here’s a list of the workshops that the Center for Information-Development Management is offering over the next few months:

  • Advanced Publishing for DITA
  • Minimalism: Creating Information People Really Need
  • User and Task Analysis for Information Design
  • Developing Quality Documentation in an Agile Environment

In our final post on the State of Collaboration we will look at issues involving localization and content conversion.

Get a Demo