Scroll Apps for Confluence
Backbone Issue Sync for Jira
AI-Powered Search for Scroll Viewport
About Us
Careers
Partner Program
Trust Center
Contact
Collaboration Hub
PDF Template Library
Feedback, Please! - Why Technical Writing Shouldn't Be a One-Way Street
For a long time, technical writing was like driving down a one-way street. We’ve sent information into one direction, and nothing came back. But since the age of the Web 2.0, this approach is no longer a best practice. Today, being a technical writer means to communicate and to interact with everyone involved – including our readers. Building documentation heavily depends on feedback, and it’s an iterative process – more like a traffic circle. New processes require new technology – it’s time to move from publishing tools to collaboration platforms.
This blogpost is part of a series about feedback in technical communication, In this article, read why receiving feedback is crucial to create helpful technical content and how a web-based collaboration platform can enable both internal feedback and customer feedback.
Positive Feedback is More than Praise
Giving feedback doesn’t have much tradition in the south-western area of Germany where I live. The locals use to say „No complaints are praise enough“ („Net g'schimpft isch genug g'lobt“). So you’ll rarely get any feedback – although feedback is key to making things better, even if we don’t get much praise. As a technical writer, I do heavily depend on feedback of any kind, in order to create helpful content that readers expect, and to give my audiences what they need to succeed.
Typically, technical writers aren't getting much (useful) feedback on their content either. Probably some pencil-jotted corrections from subject matter experts (SMEs) will fly in during a mostly too short review phase. And from time to time they also might share some enlightening additions to the documentation. But almost never technical communicators get feedback from those who they want to communicate with: their audience.
Why don’t readers communicate with us? One of the main reasons for not giving feedback is that in traditional publishing workflows, there’s no way to provide feedback both easily and reliable. The Web 2.0 movement brought us web-based content collaboration platforms (i.e. Wikis) – digital venues where information consumers can also produce content by themselves.
Today’s web-based collaboration platforms are changing the way we create, review and publish content. Providing documentation is no longer a monologue of sending content to people, it becomes a dialog instead. As a result, technical writers actually are evolving to technical communicators – finally!
The Content Lifecycle – Extended Version
In traditional documentation publishing processes, technical writers first make a plan, they’ll define a structure and do some research before they actually create and author a first draft. This draft will be reviewed and tracked until someone decides that it can be published in one or multiple formats. And finally, it is made available to the readers.
If we choose a collaborative approach, we can add a fifth phase to this process: engaging our readers. By giving them a way to contribute, we get the feedback loop closed and start communicating. This allows technical writers to improve the documentation continuously, based on the input, the questions and preferences of their readers.
We can keep track of every change in the wiki – the whole process from creation to review becomes transparent to everyone who’s involved. Getting feedback during both the Track and the Engage phase results in significantly better content quality (as opposed to some untenable wiki myths).
Getting Feedback on Draft Content
During internal review, SMEs will typically check the content, add notes here and there, close some knowledge gaps, and discuss factual errors and misconceptions with the technical authors. Editors will also review the draft content focussing on style issues, and they will ensure consistency and formal correctness. Finally, the draft is approved and is made ready for publishing.
When working on a collaborative platform, everyone who is involved in content creation will literally work on the same (Wiki) page. Social features like commenting and the ability to like and share great content help users to interact with the content – even if all participants are working from different offices or even in different time zones.
Depending on the workflow, the latest content revision becomes either instantly available to the audience, or a staging approach can be applied, where a page receives a status and is being published explicitly within a separate step.
As an example, the Atlassian Confluence collaboration platform allows users to comment on content fragments of any size or type, discussing and resolving changes and tasks without switching web browser windows. Users can add, change or delete content. Meanwhile, every change becomes transparent and if necessary, previous revisions from the Page History can be restored with a click.
Through add-ons, one could store a draft and a published version of each Confluence page. This could be done either by assigning a page status using the Comala Workflows plug-in, or more sophisticated by publishing final content to a distinct release documentation space, using the Scroll Versions add-on. Moreover, this add-ons allows you to maintain multiple versions and variants of content simultaneously inside one authoring space.
Ways to Learn from Your Readers
The other, yet more exciting part of feedback comes from those who actually use the published documentation to learn and to solve a specific task: your readers. To gather their input, a web-based documentation platform is crucial. It allows technical communicators to benefit from features like ratings, discussions, and analytics.
User Ratings for Helpful Content
The most straight-forward approach is probably a content rating feature. It allows technical communicators to gather user feedback on a page’s helpfulness, e.g. on a scale from 1–5 stars. In Confluence, this could be done e.g by using the Rate Macro add-on.
Comments and Discussions
Some readers will provide even more valuable details through page comments – if we allow them to tell us that anything could be missing, outdated or incorrect. Maybe users will have follow-up questions, or perhaps even want to share insights that extend the official set of documentation content with troubleshooting information and tips.
For instance, the PHP documentation site provides extensive user contributed notes that increase the information value significantly.
On the other hand, a large number of user contributions makes it more difficult for technical communicators to manage the feedback loop. Atlassian recently experienced that only 20% of comments on their public-facing product documentation were contextual. Any other comments seemed to be support/feature request etc. This urged Atlassian – a company that is crazy about collaboration – to close down comments on that site.
In contrast, the Atlassian blog post announcing that decision is a prime example of how fruitful user discussions can be. 60+ people commented and shared their concerns and ideas, and Atlassian listens (and answers) carefully. Thus, in some cases, comments can be too much of a good thing, but they definitively are a good thing!
In-Depth Page Analytics
The third kind of feedback comes from analytics data. Using web analytics software like Google Analytics, we can find out easily how many users search for specific terms and how long they stay on particular pages. Analytics is probably the most silent way for technical communicators to learn more on their „client’s“ behavior.
Conclusion
Successful technical communication is more than technical writing. It heavily depends on the user’s feedback to let us create tailor-made content for our audiences and to meet their needs and expectations. The best way to get there is a collaborative approach that includes both internal content review process and easy customer feedback on documentation.
Many organizations have found Atlassian Confluence to be the platform that combines both aspects in one web-based collaboration platform. The success of Web 2.0 shows that letting people participate means much more than just receiving and implementing feedback – this applies also for technical documentation.
And if technical communicators listen to their feedback thoroughly enough, there might be even a chance to get some praise … ;-)
Stay tuned for the next part of this blogpost series. Then, I'll discuss some best practices on how to build collaborative help platforms that allow technical communicators to bring their documentation to the next level.
Until then, you could try Atlassian Confluence and Scroll Versions with a free 30-day evaluation. If you have any questions, please write a comment or drop us an e-mail at info@k15t.com.
