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.


We’re Growing!

This September marks our largest ever Tech Comm class at Seneca. One of the reasons for this larger class is the Ontario government’s Second Career initiative which assists people in going back to school to retrain for a new career or upgrade their skills so that they are more employable. It’s a great program, and we are benefiting from having top notch candidates enroll in TECC.

The other reason we’re experiencing a growth in numbers is that our promotional efforts are beginning to pay off. Over the past two years, we have promoted the program through the media, related organizations, and word of mouth. Our current increase in enrollment is due to stronger industry partnerships, closer connections with the Toronto chapter of the STC, increased co-operation and relationship building among departments at Seneca, and leadership that brings all of those parts together into synergy.

I always tell our students that Technical Communication is a relationship-building profession. We need to have excellent relationships with our audience, our Subject Matter Experts (SMEs), our co-developers, our employers and clients, and of course each other. Networking is strong in our profession, not only for obtaining work but for keeping up on trends and new techniques as well.

And it doesn’t hurt to have some friendships among other technical communicators — for those frequent days when being a professional gadly isn’t always as much fun as you might think.

Each of our Tech Comm classes travels through the semesters together. By graduation, firm friendships and professional bonds have formed, laying the foundation for future success. Even though this year’s class is that much larger, I am certain the same bonding will occur. It’s wonderful collaboration, and we all benefit.


If the User Can’t Find It…

… it’s not there.

One of the many roles of the technical communicator is to assist developers and designers with making products, websites, and interfaces easy to use. Users who have to search for the functions they need get frustrated, and conclude that the product or website is difficult to use. Consequently, they are less likely to remain loyal to the companies that allow such barriers to productivity. This results in lost revenue and a tarnished reputation.

As user advocates, technical communicators help companies avoid such pitfalls. With a continual focus on how the user will interact with the product, technical communicators alert developers and designers to functionality that may seem straightforward but which creates roadblocks or traps for the end user.

One of the ways we ensure usability (meaning a user can accomplish their goals with the product) is to approach product development from a task perspective. What is the user trying to do with the product? This task orientation engenders a different architecture than a pure function-based approach. It supports user performance rather than offering a broad menu with a range of choices and expecting the user to know exactly where to go and what to do. It often guides users into a workflow that makes them more productive, and helps them work faster. This also increases their satisfaction with the product.

It’s a matter of focusing on how the user will accomplish their tasks with the product instead of what the product can do for the user. This HOW over WHAT mindset is often foreign to systems analysts, developers and designers who are immersed in the features and functions of their creations.

A product can incorporate a host of features, but if the user cannot immediately recognize how a particular feature helps achieve the task at hand, those features are meaningless.


Ideal Second Career

Changes in the economy often mean unexpected layoffs and situations that prompt one to think of a career change. Technical communication is a profession that allows you to leverage your prior background and training into a new career.

No matter what industry you worked in, you can take those skills and reapply them in a new way, by becoming a technical writer, a usability specialist, a content provider, or an instructional designer.

Has the market for bakers shrunk? Consider the equipment used by professional bakers, and others in the food service industry. It all needs documentation. Manufacturers of food service and restaurant equipment need website content, interface advice, and even training materials.

With existing knowledge of any field, you can transition easily into a new career writing and developing information about that industry.

Technical communication relies on skills that involve plain language and procedural writing, researching, interviewing, audience analysis, and project management. Good communication skills are necessary, but do not have to be Governor General’s Award-winning calibre. It is sufficient to be able to write clearly, concisely, logically, and appropriately. It is more important to target information correctly for the audience than select a poetic turn of phrase.

The writing and facility with technology can be taught. Seneca’s 1-year program in Technical Communication teaches the basic skills, tools, and approaches needed by technical communicators. The certificate you receive upon graduation from the program indicates to employers that you have the processes, skills and understanding to communicate complex, technical information to a range of audiences, no matter what the industry.

In good times or in bad, communication is always required, and practitioners who know how to get a message across to the target audience are always valued.


Building Bridges

Technical communicators are always building bridges — between technology and its users, between content and design, and between groups or individuals so that the flow of information can be smooth and easy. In that way, we are always making connections. We connect people with the information they need to solve a problem, perform a task or answer a question. We often connect people with other people, even though there may be another type of interface between them.

Continually standing in the gap, as it were, we see both sides of a situation. We are also very familiar with the chasm that can exist between information and understanding. If you’ve ever fallen into that chasm yourself — flailing helplessly because you don’t “get” whatever it is you’re supposed to be getting — you know how much of a relief it is to finally have that dawn of understanding when the lightbulb goes on and what you’ve been struggling with makes sense.

That’s a situation our students confront all the time. From their own uncertainties, they forge structures that help them get from the unknown to the known. Learning to build those bridges makes them very effective at creating similar structures for their readers and users. It is our empathy with our target audience that helps us correctly choose and shape the information we convey so that it does the job intended.

You don’t have to be an engineer to be a good technical communicator, but it helps to be able to think like one.