This article was originally published in ISTC Communicator, Spring 2017.
We all have similar challenges with our content; we’re all trying to create the highest quality content possible while coming in on time and on budget. The trick to being successful is paradoxical.
Today’s enterprises are facing challenges when creating, managing, and delivering content. Product managers often believe that they need to create more content to become a strong presence in the marketplace. It’s a misdirected effort to drown the competition out with sheer quantity. The truth is that end users find more value in a focused message that is well targeted and addresses the specific needs of the audience.
The challenge is how to write a message that meets the demands of your audience. When middle management says ‘write more’ our response should not be ‘how much more?’ but rather ‘let’s write more targeted content.’
Content creation challenges
We have constant pressure to improve the efficiency of the content creation process: write more, write faster, maintain different releases and versions. This is particularly hard to do when you have budget cuts, you can’t hire more personnel, and your tools can’t deliver on evolving requirements.
Correct, complete, and consistent
There are some interesting challenges to ensuring correct and consistent content. Our goal is high-quality content that doesn’t take two years to create. That sounds like a long time, but it’s often the case that the product changes so much, so frequently that there is a huge backlog of changes that need to be made. But the constant pressure of creating more and more content means we’re often sacrificing ‘correct and consistent’ for‘as correct as we can get it for this release’ and consistency gets thrown out of the window. In addition, the more content we create, the more time is needed to update it for a particular release.
If management asked for five new books for the last release, that’s five extra books you will have to forever maintain and update. The initial time to create those five books may have been an effort you could afford, but over time, the maintenance on so many additional deliverables takes its toll and spreads us too thin to even meet the threshold of ‘mostly correct.’
The problem of generating and maintaining too much documentation has a domino effect, of course, because not only do you have to create and update those guides, you have to send them all back through a quality assurance process that adds days or weeks not just once, but to every release. Your already tight schedule becomes increasingly difficult to adequately meet.
At this point, many technical publications managers insist on more writers for their teams but are often denied because management doesn’t look at the absolute number of pages or topics to maintain, they look at the developer/engineer-to-writer ratio, which in most circumstances hasn’t changed, and deny the request. Budget increases are also rare unless the manager can get solid metrics on the cost per page and the number of pages they’re creating and maintaining over a year. These are often slippery, ever-changing numbers that are extraordinarily difficult to put an actual value on. Technical publications managers are left with nothing else to do but put more pressure on the writers to ‘work faster,’ which means(intentionally or not) lowering the bar for quality content; correct, complete, and consistent go down the tubes.
Unfortunately, this is the beginning of the downward spiral on the content quality. Once quality is sacrificed for quantity, your end users will notice and will be vocal in their complaints. That negative feedback will directly impact the technical publications department six to nine months down the road; the entire department will be taken to task for not working hard enough, even though you’ve never worked harder to create more content.
The term ‘thankless effort’ springs to mind. It’s around this time that the technical publications departments get lots of turnover, both of their over-worked under-appreciated writers and the managers who ‘couldn’t make it work.’ If you’re feeling like a hamster on a wheel, there’s a reason for that. We think it’s time you stepped off the wheel and started working smarter.
In this digital information age, with content instantly at our fingertips, our end users aren’t expecting last year’s content. They’re expecting every piece of documentation to be completely up to date whenever and wherever they access it. Some do better than others when it comes to timely content releases. At the lengthy end of the spectrum, some departments can take up to two years to update documentation to match reality, only to know that the moment they publish it will be out of date again.
Most of us are aiming to be at the other end of the spectrum: departments that have mastered the content cycle and can publish weekly or even daily. If your department isn’t capable of providing
weekly updates for documentation, then you have room for improvement.
Working with Agile development teams
Another huge challenge is aligning content development with product development. With Agile development gathering more and more impetus in development circles, documentation departments are increasingly being asked to make the change as well. We could write an entire article just on how to
align with Agile development but it comes down to these main requirements:
- Demand detailed user stories on each new or modified feature. This keeps the team on track and will ensure you can do your job quickly and easily.
- Insist on creating only focussed, task-based content for these features that follows the user story they’ve identified. This keeps the content you need to create focussed and highly valuable to the end user. You can generate the content relatively quickly because it’s so focussed.
If the Agile team can stick to the best practices of Agile development, authoring will not only be
possible, authors will be able to create content as the feature is developed. The further they
stray from creating valuable user stories or building what they say they will build, the more
impossible your job will be, especially as part of the same sprint.
Content management challenges
We spend most of our time frantically creating content and don’t spend enough time applying
content management best practices to our source files. There are a couple of reasons for this:
1. Not many people know the best practices for source-file management.
2. It’s a (one-time) disruptive process to implement and we often delay it until there’s a ‘good time,’ which never comes.
The problem with source-file management is that we don’t do it well. We often use shared file systems, with or without versioning, and might include automatic backups or snapshots. This would be fine if we were all creating one-use documentation but most of us are creating living documents that get updated for new versions and releases.
Standard (poor) practice is to copy one release’s folders and files, create a duplicate, rename it, and then start working on it for the new release. This is, unfortunately, one of the worst ways to manage source files. It’s not long before you have a massive shared drive of duplicate after duplicate of files, graphics, and folders. It doesn’t take long until only the person working on that project can tell where the real files are right now, and trying to determine the location of files from two releases ago is a heart- thumpingly high-risk procedure. Add in all the snapshots (hourly, daily, weekly) and you could easily be fishing through a million files trying to find the one that is correct.
We call it the spaghetti of doom. Everything is there (probably), but finding it will always be problematic.
For regulated industries, documentation departments need to be able to identify where and how content has changed, including a complete audit trail. Each file must be managed intelligently, with few or no copies of any content object because that would call into question which file is the authoritative source.
Instead, a database is used to store files so that authoritative sources are preserved, copies are
avoided, metadata is managed, and a complete audit trail of every change is always available.
Files never move, are never copied or emailed, and have a complete history attached to them. They are a single authoritative source (a singular source for each information object) and utterly reliable. When you work on the next version of a product, you work on the same file so the content object continuity is
never severed. The last release information is still stored (and can be retrieved), and the next release can be safely started. You can look at the history of the content object to see what it contained last release, six releases ago, or at any point in the history of the object since it was first created.
We should all be striving for such control and visibility into our source files, whether your
industry is regulated or not.
If nothing else, the potential to confidently reuse content once it is carefully managed should immediately strike you as both more possible and more controlled.
There are lots of corollary best practices in content management, but managing your source files in a database is a key factor to managing your content effectively. The best databases for technical publications content, whether you’re using DITA or not, are Component Content Management Systems (CCMS). There are lots of choices out there so it's worth the effort to do your due diligence, identify your functional requirements, and pick the right one for you.
Review workflows are one of the most visible and obvious challenges that we face every release. It helps that there is an identifiable hand-over date for content but getting back timely (and helpful) feedback is where things become wibbly wobbly. The enterprise wants the documentation ready prior to release
but leaves it as the last part of the product to update before release, which is a tricky
expectation to meet.
If your development teams are using Agile, then you’ll sometimes avoid this last-minute frantic push to get everything reviewed, although some enterprises still insist on doing a complete end-to-end review on an entire deliverable, leaving you in the same place as any non-Agile writer.
Getting another department to stick to your deadline is always challenging but the keys to this are providing good review tools, making reviews simple for reviewers and authors, and ensuring that you have highly visible due dates.
Publishing is often a mad rush to get a document set out the door, usually to match a product release. But when software fixes are going into the product right up until the last minute, publishing can be quite a challenge. Mix in all the complexity of multiple outputs and a robust user experience and, if you don’t have firm control over your content and your publishing, you’ll end up working weekends and nights just to ensure that your content gets out the door successfully.
The challenges for publishing all revolve around what your end users need.
- Who are your end users? Are there secondary end users, such as internal stakeholders (Training, Support) that will rely on your content?
- How will they access your content? This includes the physical situation, devices, formats, and so on.
- What do they do? Under what pressures?
- What is their understanding of the topic? Do they have domain expertise?
- What access control and security will you need?
- Where will you publish?
- Who will be responsible for publishing and testing published content?
- What features can you implement that will make the user experience of content optimal?
- How can you minimize the publishing effort with appropriate tools, automated processes, and testing?
The goal is push-button publishing to provide the content in a format, location, and experience that your end users need.
Reaching that goal is a matter of in-depth planning, testing, and appropriate tool adoption.
Once you know the challenges that your enterprise faces, you can start finding the solution that’s right for you.
We recommend a two-pronged approach to solving the core problems in technical communications:
1. Write focussed, task-based content. Spend less time writing. Put your effort into planning.
2. Choose the right tools to let you more easily manage your content, workflows, and publishing.
Write less, but more focussed content
Push back against more content just for the sake of more content. There is no need to create a tome of information for the masses. Instead, create content that is targeted to your (specific, clearly identified) audience. Focussing content on your end users will let you write for the business goals rather than the product features. Ask yourself ‘what do they need to do with this product’ rather than ‘let me tell them how feature X works.’
Once your content is streamlined to only the best, most focussed content, solving all of the other challenges also becomes less complex. There’s less content to manage, review, and publish.
Manage your content intelligently, implementing best practices and using the right tools for you. A database such as a CCMS can help you apply best practices and get you moving in the right direction.
A CCMS can also enable extensive reuse, content profiling, and save money with translation.
The more you know your audience, the better you can understand and meet their needs. Keep in mind that your primary end users are not developers, marketing, support, or some other business units. You need to know what the people who consume content really need.
You may consider internal stakeholders as your secondary audience but focus on your end users first.
User analysis combined with end-user feedback through various channels (Pre-sales, Support, Marketing) will get you reliable information on what they know, how they work, and what they need. You can create user personas from this information to encapsulate in a hand-to-use format for authors. You may even be able to re-purpose user personas from Marketing.
There is no such thing as too much planning when it comes to technical documentation. The more time you put in up front on quality user analysis, end-user business goals, publishing, user experience, and testing, the more time you will save when it comes to authoring, reviewing, and publishing.
Information architecture and content strategy are two roles that revolve around planning: information architecture is planning how you will manage your source content and content strategy is planning the published content. Both are integral to meeting the challenges you will face.
Planning may involve new tool selection but don’t begin by changing your tools. A tool change should come as a result of careful and in-depth analysis of what and how you need to deliver. Once you have concrete requirements, identifying that you have a tool gap and then finding the right tool becomes much easier. You’ll also find that your requirements gathering will help you sway middle management and connect with potential vendors.
Your tool selection is going to be integral to delivering on your plans. If your current tools
can’t make your plans a reality, then it’s time to upgrade.
You need tools that meet your specific requirements in the areas of:
The answer to high-quality content that is on time and on budget is not a matter of ‘more content.’ Do so and you’ll overwork the authors, while simultaneously diminishing the value of the content.
The emphasis has to be on extensive planning and analysis, combined with appropriate tool selection. Combine that with concise, focussed content and you’re well on your way to creating the best content for your end users.
Bernard Aschwanden founded
Publishing Smarter to focus on
communications. He is an Adobe
Certified Expert, a Certified
Technical Trainer, and the past
President of the Society for Technical
Communications. He trains, writes extensively,
and presents internationally on communications,
publishing, and single sourcing content.
Jacquie Samuels is a DITA consultant
with Publishing Smarter. She is versed
in all things CCMS, a graduate of the
Seneca College Technical
Communications program, and a
senior writer and editor. She consults with clients
helping them develop a content strategy, performs
content analysis, and assists in picking the right tools
for the job.
Share on Facebook
Share on Twitter
I'm busy working on my blog posts. Watch this space!