Got Problems? Get Tech Comm!

Website problems of could have been greatly reduced with technical communicators on the job

Like most Chief Executives, President Barack Obama could have saved himself a  whole lot of trouble if he had hired a technical communicator. became a public relations nightmare for his administration due to problems with enrollment and numerous user errors as millions of people tried to sign up for government health care subsidies.

Those are precisely the kinds of problems technical communicators are trained to solve. Technical communicators are advocates for the user. They carry out extensive user testing of products and websites, and contribute to a better user experience on every project. Having such practitioners involved in development of the site would have greatly reduced the number of user errors, and made the entire process smoother.

David Auerbach writing on notes that large scale projects with multiple contractors working in isolation are not only going to miss problems, they often create them. Remember the carbon dioxide scrubber mismatch on Apollo 13?

Technical communicators concern themselves as much with the big picture as the technical details, so they would have ensured those groups communicated with each other, or at least shared information. It’s a technical communicator’s role to think each project through from beginning to end, especially from the user’s perspective — and then ask the questions that need to be answered to enhance the user experience and support user performance.

Apart from the obvious problem of heavy load, which should have been anticipated by the server administrators, subjected users to confusing navigation, meaningless error messages, a broken sign-up process, and information privacy issues.

Executives from CGI Federal, which handled most of the project, claimed testing began too late and the website rollout was premature. Technical communicators, while handling the documentation tasks related to web content and product development, begin user testing as soon as they can get their hands on a stable working version. Consequently, errors are found during early stages of development, allowing bug fixes to be made quickly and inexpensively as the product is being worked on, instead of after delivery when errors are not only embarrassing but much more expensive to repair.

Further, Gov. Chris Christie, R-N.J. pointed out that the government was sending out mixed messages, telling people they could keep their policies in one place, then elsewhere telling them they couldn’t. That’s another area where technical communicators add value to an organization: they ensure all communications are clear, consistent, correct, and appropriate for the target audience.

Of the myriad issues plaguing, technical communicators could have helped with most of them. Technical writers, now called technical communicators because they do so much more than just write, have always worked to make technology easier to use and understand. Technical communication is practical communication, intended to help someone perform a task, answer a question, or solve a problem. In institutions, government, corporations, and businesses large and small, technical communicators contribute to reducing customer support costs and improving user satisfaction.

For more information on the Society for Technical Communication and its professional members, see To apply for the Seneca College Technical Communication post-graduate certificate program, see


Employing not Exploiting Students

I’ve recently had another request from a company with a tight budget to engage some of our students on a worthwhile project. I’m very keen on helping students get involved in real world projects while they are still studying. There is great value in that for them. They get experience and the opportunity for a good reference. Frequently, they also get a portfolio item, something they can point to and say, “I worked on that.”

Unfortunately, the latter is often the only thing of value that is offered them when a company seeks student labor to do something they would ordinarily have to pay a professional to do. I advise students against doing something solely “because it will look good in your portfolio!”. They have many opportunities to create something for their portfolio through school projects and co-op placements.

What is more valuable to them is a legitimate work experience, not an exploitative one. Students have up to date skills that they are bringing to the employer, skills that they’ve paid a great deal in money, time, effort, and often stress to acquire. They should be paid for their time. Our co-op employers not only pay students a fair wage, but they provide other opportunities such as on the job training, mentoring, and occasionally bonuses.

Exploiting students because you have a tight budget is simply not acceptable. Be creative; pay them something and sweeten the pot for them. Can you provide bus passes or free products/software? Will they get extraordinary access to senior people in your company to learn things we cannot teach in school? Will you commit to giving them a reference, and refer them to other companies for better paid work?

Make it worth their while to help you out, and you will not only get top quality work from eager and motivated people, but you’ll be establishing a valuable relationship as well. See the opportunity as an investment in their future AND yours. Your reputation will grow as well. In this climate of widespread social media, you want people as connected as students to say good things about your company and help build good will. You can’t put a price on that, and it’s worth every penny.


FSOSS 2009 & Documentation

Concluding Open Source week in Toronto, Seneca held its annual Free Software and Open Source Symposium (FSOSS) yesterday. I was privileged to have the opportunity to speak about documentation for open source projects.

What is truly exciting about open source development is the collaborative and community aspect of it. I love the synergy of keen minds working on a collective project. Documentation too benefits from having multiple people contribute to and review it. While there is the danger of it sounding a bit like “authorship by committee” I think that problem is easily avoided by having an editor who is responsible for smoothing out the voice.

As we drift more toward topic-based writing that addresses user tasks rather than features, we can accommodate multiple writers because the style guidelines for topic writing are very straightforward. Publishing in an open source environment often involves Wikis, which are an excellent collaboration tool. Marry the idea of topics with a wiki that allows anyone on the team to contribute to the project and you have some excellent documentation that can be developed quickly.

I still encourage documentation plans, and reviews/approvals as part of the process, but generating content is much simpler.

I also still emphasize authorship, meaning document ownership. I don’t mean that someone gets to “own” the documentation in a proprietary way. Open Source is all about moving away from that idea of singular intellectual property toward a collaborative work package that represents the best a group of people can produce. Document ownership is simply taking responsibility for your contribution. Even though other people will look at it and edit it, each author does the best they can to make the documentation excellent.

Another point I brought up in my presentation was that documentation really includes all of the information, communication and knowledge around any particular product. Documentation is a way to add intelligence to the product during development to create a superb user experience. This can be as simple as putting informative labels of data fields that are to be filled in. The example I gave was of a web form that provided for a 10-digit telephone number, without hypens. The user doesn’t know that, however, until they start filling in a phone number 800-555-12 and run out of space. It takes very little effort to indicate how the user should input things like phone numbers, dates, postal codes, and so on.

Of course I recommended that technical communicators be involved in producing the documentation for Open Source projects. I know where you can get some if you want them.

The recorded version of my presentation will be available on the FSOSS web site shortly.


Dependencies: The Bane of Efficiency

Students in the Technical Communication program learn how to manage their documentation projects. I’m fond of drawing the parallel between the Software (or Product) Development Life Cycle and the Document Development Life Cycle. They both have the same phases.

The keys to project management of course are to control scope, supervise resources, and manage dependencies. It is this last item, dependencies, that often gives project managers their biggest headaches.

A dependency occurs when one part of the project cannot go ahead without another part providing input or a trigger for it. For example, technical communicators cannot complete documentation on a product unless they have a stable and complete version of the product to work with. Their work is dependent upon something produced by someone else. No matter how efficient they might be, they are brought to a halt quickly when some dependency is not ready.

Because so much of what we do as technical communicators depends upon actions taken by others, we develop skills to ensure others do what we need them to. You might think of us as professional gadflies. We coax, prod, chivvy, encourage, and even annoy those upon whom we are dependent. We relentlessly follow-up; we continually pursue loose ends. We check and double-check. We ask, “Is this ready yet? When will it be ready?” — questions others often don’t want to hear.

Our tactics are not enjoyable but they are vitally necessary. And too frequently, it is the technical communicator who ends up driving the project forward simply by virtue of needing certain things done by specific dates.

If your projects are sluggish, and efficiency is hampered by too many dependencies, get a technical communicator on your team and watch things start to happen.