Feedback, Please! - Part 2: Building a Web Help Platform to Get the Crowd Involved
Comment
Feedback, Please! - Part 2: Building a Web Help Platform to Get the Crowd Involved
“No one reads documentation, and nobody gives feedback on it.” This phrase is bad news for technical communicators – but it’s not the whole story. What actually happens in reality hinges on the way we manage and distribute technical content. (Protip: Host it on the web and invite everyone to get involved).
This is the second part in our blog post series about the benefits of crowd-enabled documentation using a collaborative approach. In this post you’ll learn how to get readers’ feedback on documentation easily by building collaborative web-based help content that allows technical communicators to elevate the quality of their work to the next level.
Does Anyone Actually Read Manuals?
When one queries groups of tech people, one learns quickly that most of them don’t admit to reading manuals. It seems that reading docs is a bit ‘uncool’ within these (and many other) peer groups.
Recently I attended a corporate hackathon, as a technical writer. At this event, I had the opportunity to look over the shoulders of software engineers and consultants to see how they actually use our product (and “my” product documentation) to compete in a challenge.
What I saw was striking: Although nobody had admitted to reading the docs, I could see several times how the competitors opened the web-based version of the help content and engaged with the desired information in a very targeted and efficient manner. They knew exactly what to find, and they took full advantage of code examples provided in the docs to gain an edge.
And yet another discovery: Nobody used the PDF version version of the documentation that was also available to them.
How to Build a Platform to Get the Crowd Involved
In the first part of this series , I explained why feedback from both internal reviewers and from our readers is so important for building great technical content, and why it requires a bit more than a desktop word processor. As an example, I introduced the Atlassian Confluence collaboration platform to follow an agile, feedback-enabled approach for technical communication.
Now that we know how important feedback and collaborative content management platforms are, let’s have a look at three approaches to building a web-based feedback-enabled documentation site to get the crowd involved.
Option A: Public Collaboration-Enabled Knowledge Base
Everyone knows Wikipedia, but many people don’t know that public wiki sites also work great for businesses of all shapes and sizes to share documentation with their customers. Instead of deploying Wikipedia’s MediaWiki engine, businesses are typically best served by platforms that meet enterprise needs like extensibility, permission management, and professional support. These enterprise platforms also focus on advanced collaboration and content management features.
Computer Associates, for instance, has built an impressive DocOps platform based on Atlassian’s Confluence that is available to the public via https://wiki.ca.com . Users can even rate and comment on pages to provide feedback. Analytics data for these actions help their 300+ contributors to understand users’ needs for a complete, searchable, and consistent content offering.
Option B: Web Portal with Collaborative Back-end
Another approach to providing crowd-sourced content to the web is to separate editing from viewing. This means having a collaboration platform for content creation, but publishing its content through a separate web interface that doesn’t actually look and feel like a wiki. Users won’t know (unless they are told) that what they are seeing is actually wiki content.
To bring their developer documentation to the web, Atlassian uses Scroll Viewport , an app for Confluence by K15t. Scroll Viewport separates the task of editing Confluence content from how it is published and viewed using an in-style, lightning-fast ‘viewport’.
When choosing the viewport approach, collaboration takes other forms. Users might provide feedback through Confluence’s built-in comments feature that’s optionally accessible from the viewport. Alternatively, an external discussion platform can be integrated – like Disqus – which Atlassian chose for its developer documentation site.
Option C: Reviewing Static Web Content
The third approach to implementing a feedback-enabled web platform for your documentation is by providing a static HTML export of your content, and adding an external discussion platform. Tom Johnson applied this method first in order to get reviewers involved in his DITA-based content, and then once again when he discovered ways to review static web content built from Markdown using the site generator toolchain Jekyll.
The static web content approach can be ideal particularly if there are technical or organizational reasons why the content creation platform cannot provide unique collaboration features, or if it must be physically separated from the public-facing documentation site.
By the way: For Confluence, there’s also a static HTML export option available using the Scroll HTML Exporter . By customizing the export theme, you can get the desired look and feel to let documentation content seamlessly integrate into an organization’s web experience. It also allows integrating the Disqus commenting platform into a customized theme to gather user input for each documentation page.
Either way, choosing a web-based platform for documentation is a crucial step for both internal review and for getting feedback from the audience in order to get everyone involved.
Go Forth and Collaborate
The answer to the initial question of whether anyone actually reads documentation is a resounding “Yes!”, although it’s true that some of the more tech-savvy readers won’t admit that publicly. In fact, many don’t use documentation in a conscious way – it’s just an essential part of how they work.
But actually, these users might not ever read clumsy ‘manuals’ (printed or PDF) which force them to dig through everything to find what they need. Instead they consult online, web-based documentation, where every page is page one.
In their day-to-day routine, software engineers collaborate constantly over code, ideas, and problem solving. This is why our documentation set should follow their working habits and provide collaborative features (described in Part One of this blog post series).
By the way: This idea isn’t limited to software engineers. Almost everyone likes up-to-date content available in their web browser, and documentation that is search-enabled, browsable, and shareable. Not everyone might take advantage of feedback channels, collaboration features, and crowd-sourced content, but some people certainly will. As a result, they will experience increased value, and we can continuously improve our technical documentation contents based on their feedback.
For us technical communicators this means finally moving to web-based, contextual, and collaborative platforms to author and deliver technical content, in order to get valuable feedback from our readers and to bring our documentation work to the next level.
Feedback, please!
Now it's your turn: Please tell us what you think, and discuss this article in the comments below. Do you need help building a collaborative documentation platform with Confluence and our content management apps? Drop us an email at hello@k15t.com.
