barrybaldwin.net

With the advent of Open Source CMS software like Drupal or even blogging platforms like TypePad, WordPress, and others, there’s really no excuse for not having an easily managed website that enables rapid, problem-free deployment of new content. There’s even a dizzying selection of plugins for these systems that enable all kinds of RSS feeds, video delivery, and podcasts to deliver truly multimedia content. Time was, you needed to hire a developer to build custom code that may or may not deliver as promised, depending on the skill of the developer and the client’s budget. Those kinds of custom systems are still out there, and some large websites really do demand that. But as these open source tools become more powerful, the need is becoming less and less.

Documentation teams should take advantage of these powerful new tools to author official content with the same social networking and information architecture features that many new web startups are now based on. Of course, the tricky part is developing a documentation strategy and choosing the right tools to fit that strategy.

Browser-Based Beats Built-in

Many software companies still deploy their online help using proprietary platforms such as RoboHelp or RoboHTML. The platform is mature and Technical Writers are comfortable with them. Those two things alone count for a lot. But Technical Writers are at the forefront of technology, and working with software development teams, we are uniquely positioned to take advantage of new technologies.

Many software makers maintain user forums, and these are great for maintaining great information and keeping your your users engaged and enthusiastic. But forums are notoriously weak at enabling users to find the information they’re looking for if it is already out there somewhere. Wikis offer a semantic structure to all that information and official documentation teams can easily review content for accuracy and readability. We can also link this content to other resources such as white papers and tutorials.

Community-Based Documentation

I’ve written before on backing away from context-sensitive help to workflow-based help. Of course, this context-sensitive to a degree, but the point is to get away from documenting software tools in isolation, and move towards documenting a work process more like a tutorial. Social networking and Wiki tools can be powerful tools for collecting best practices from fellow users and sharing all of the possible variations. Documentation Teams would then become responsible for editing, verifying, and maintaining those procedures based on real practices rather than creating from scratch based on expected practices.

Introduce a Feature’s Real Role and Purpose

There’s a much-touted statistic that 80% of users only use 20% of the features in a given software package. Those figures have been thrown around to illustrate the excess in the development process that is detached from the end user. However, if the feature has a real benefit to productivity or effectiveness, why not use documentation to advertise that? Some software packages can be set to show a popup advertising a feature at startup, but what about a featured tutorial? Consider developing documentation in a “lessons” mode that can walk a user through a procedure.

Help Users Dig Deeper

Hypertext enables every term and name to be linked to some deeper explanation. Deep-diving isn’t for every user, but the easier we can make it, the more engaged the user will become. Engaged users become loyal users. Especially if they feel that the software maker is not only speaking to them, but listening to them. MS Office help does this to a limited degree, but I’ve always found these drill-down links to offer inadequate and unsatisfying explanations. They just don’t speak to how I use the software, and I suspect I’m not alone in this feeling. Hypertext takes up very little space compared to the application itself, so there’s no need to skimp. These links can point to Wiki articles, procedures, white papers, and even marketing materials if that’s part of your documentation strategy. Don’t be shy.

Don’t Wait for Release Cycles to Add New Content

Depending on your documentation platform, you may be able to embed RSS feeds into the documentation. This is one good reason to build your documentation in XML rather than HTML or some proprietary platform. XML can be parsed into Flash, XHMTL, various DTP software such as InDesign, or exported into an SQL database. If documentation is maintained on a web server and delivered via RSS, we can offer users news, updates, and information in real time.

Dedicated Browsers Are on the Horizon

Looking further down the road, Mozilla is currently developing Prism, which will allow Web Applications and pages to run fully integrated in the desktop. We don’t even have a working beta of this yet, but while the main thrust is to put Apps like Google Docs and BackPackit on the desktop, documentation can also leverage this to create constantly refreshed documentation. As this application matures, the documentation world can push Mozilla to address specific needs.