Starting a Revolution in Technical Communication

The Lecture

Miriam Lottner of Tech-Tav gave a lecture at the recent Israeli Technical Writing Conference that has started a revolution.

The gist: ten years ago we were writing PDFs and CHMs, and today we're writing PDFs and CHMs. Meanwhile, vast numbers of people around the world are now turning to Google, blogs, forums, Wikipedia, and so on to find information. If five years from now, the only thing we do is write PDFs and CHMs, we're soon going to be out of the loop.

My own take on this is: we exist to smooth and enhance the experience of the user. If the only information they need is from the programmer, we function as rapidly less-needed middlemen. How can we stay relevant?

The Aftermath

Following the lecture, Miriam received hundred of comments and emails and held conversations with Paula of WritePoint, organizer of the conference. A blog and Facebook group were created. Paula gave over the lecture at the last Jerusalem Technical Writing workshop, and Miriam gave over the lecture at least one other time (possibly more).

They decided to host a think-tank in Tel Aviv to spur innovative thinking in the field.

The Meeting

Tonight, we held a first meeting at Check Point's offices in Tel Aviv. I eyeballed about 75 people in attendance.

Miriam chaired the meeting. She had set up circles of chairs within the room, each of which was meant for a small group and contained a sketching board with a question that was supposed to spur creative solutions within the field of technical writing.

She began with an opening presentation: The world is changing fast, and the non-US world is changing faster than the US part. You can't assume that people outsource to India and China only because it's cheaper, but we (US, Israel) produce better quality. Even if this is true now, it won't be true for long: Indians are also smart, and much more numerous and growing.

In this economy, cutting technical writers is easy if they appear to be giving less value than training and customer service. And that's going to happen more and more as people turn to alternate sources for information.

How can we create services that help companies sell more products?

At the end, we followed up with a few more points:

- Consider the market (by age, profession, gender, etc) for your product to determine the correct documentation types: video, PDF, web, etc...

- We are not concentrating on specific tools, since a) some of the participants sell tools, and b) these tools may not be what we need in the future.

The Brainstorming

These were the questions and summaries of the answers.

How can you convince an intransigent boss to change things?

- Understand your manager's actual limitations
- Clarify what changes you want
- Arguments: you can reduce customer support, increase branding, increase customer contact, increase customer satisfaction, achieve a more effective use of time
- Assure boss that changes won't "rock the boat"
- Additional argument: Increase flexibility and accessibility of information

If you had two weeks of no work, what would you do with the time?

- Research your industry and other industries
- Learn skills and your own products
- Review your own documentation and cut inefficiencies
- Take a break, recharge
- You can work on these, even without two weeks of free time

How can we make documentation more efficient or faster?

- Minimize documentation
- Cooperate more closely with R&D and Customer Support
- Single source
- Centralize access to documentation, so as to share what we're writing
- Offer quick guide documentation and/or less perfect documentation before offering the complete and full documentation. In some cases, after the quick documentation you need only add responses to FAQs. [This was my contribution.]

In an agile documentation process, what can you do?

- Work with developers
- Peer review
- General knowledge of entire product for all writers to ensure flexibility
- Aim for no downtime
- Minimal sized texts, modularization

How to argue with boss that a GUI screen flow document is wrongheaded?

- First off, the participants agreed that it is better to document tasks than a comprehensive GUI layout, although it might be necessary in certain circumstances, such as when you have no idea how GUI will actually be used
- You can save on training. Actually, to create the documentation, find out what trainers actually teach and that's how you should document.
- Find out what end-users or field engineers really want
- Mature companies do task oriented documentation; best to start the documentation this way
- Examine competitor's documentation
- Especially, you don't need to document all confirmation dialogs
- If you must do GUI oriented, add task oriented diagrams

My Response

I'm fairly excited to be part of a revolution. Kudos to both Miriam for spearheading the issue, and Paula for recognizing and helping run with it. (I don't know all the background details, so it's possible the ideas were jointly developed by them and others.)

The points Miriam raised in her lecture are exactly right. Although I don't see the need for plain old PDFs and CHMs disappearing as quickly as she does, it's entirely true that companies, products, users, and writers will benefit if we can use all the new tools for disseminating information at our disposal.

The meeting was run well, and the participants were active and interested. The questions got our juices flowing and got us to share our best current procedures with each other.

Fear

But I promised Paula to write something negative, so here it is: there's a lot of fear of change. Fear that all the companies and managers will resist our ideas, but just as much fear in the room about proposing new ideas that really break boundaries.

Big companies look at their documentation as a representation of their company. Unless the documentation looks serious and business-like, they fear it will reflect poorly on the serious and business-like image they want to project.

Managers are afraid of releasing "poor" documentation, because of what may happen if a user trips up on it. This is certainly the case for million dollar equipment running major telecommunication exchanges that lose $10,000 if they're down for one minute. But most documentation isn't like this. In many cases, poor documentation put up hastily on a Wiki will be corrected and supplemented by users on their own, saving everyone a lot of time.

Writers are afraid to propose radical ideas to our companies and bosses, because we don't want to lose our jobs, especially not now. Well, that's how it goes. Even if we propose to continue doing what we're doing, but add some new types of documentation to see how it goes, we need managers to scare up money and time allocations that they don't want (or have) to spare.

Even Miriam seemed afraid at this meeting to ask the really radical questions that needed to be asked.

"Work closer with R&D?" "Peer review?" "Learn new skills?" These are hardly the answers that revolutions are made of.

Challenging Entrenched Ideas

In my opinion, we need to start challenging really entrenched ideas. For instance:

- How many of us write in black ink? Why not blue or multi-colored? Apple's revolution was a design revolution as much as a usability one.
- Why do we write in portrait, and not landscape or diagonally? Take a look at Yahoo's home page; why don't our documents look like that?
- Why are we writing linear narratives? Could we write dialogs, plays, speech bubbles, cartoons, or poems?
- People love learning from games. Can we convert our documentation into games? Can we make the pages into collectible cards, embed RFID chips, make them scannible and come alive when exposed to a video camera?
- How do we transition large documents to videos and still retain all the information? Can we do it in Flash without an inordinate amount of extra work?
- Can our books be broken into pieces? Can the pages be broken into pieces and stuck on the side of the computer?
- Can we add humor and other entertainment value to our documents so that people want to read them?
- Can we turn them into puzzles or contests? For instance, after reading the document, you take an online quiz and if you pass you get $10?

I think the people in the room were capable of adding to this list, but we needed more audacious questions.

Conclusion

Miriam said that we will create specification and working teams to further the ideas discussed.

My proposal for "next step": Let's brainstorm some really new, really good ideas and solidify a few of them. Then let's take them to our companies and see what we can do.