Technical Writing Vs. Narrative Fiction, Part 4

The last of a 4-part series.

Technical Review
After a technical document has been written—or changed significantly from an earlier version—it needs to be reviewed for technical accuracy by a subject matter expert. A tech writer needs to learn all she can about the feature she is writing about (be it the integration of disaster recovery software or a new part of the user interface), but to ensure accuracy, she must often rely on the people who designed, engineered, and tested the feature. So, before a tech writer can say a guide or help topic is done, it needs to be reviewed from a technical perspective. More than once, if there's time.

If you are writing a novel that has many medical or scientific facts and concepts, and this is not an area of expertise for you, then you probably want somebody who knows more than you do to read your manuscript. Even if you interviewed a subject matter export and maybe even visited her at work to see what it’s like to be an emergency room doctor, getting the expert to do a technical review of your book is necessary to ensure you get the details right. Get more than one expert to read it if you can. That way you get different points of view, different feedback, and different ideas.

Peer Edits
Peer editing is a term we use in the tech writing biz. When you finish a draft of a guide, you want another writer to check it for consistency, logic, structure, and corporate standards, and to give a good proof reading. Getting a peer edit on your documentation is not just a good idea but is necessary to ensure you’re not distributing sloppy, confusing material. Sometimes you don’t have the time to get another tech writer to review a guide, and you just have to be your own peer editor.

There’s no time to let a draft of a user’s guide breathe. You can't let it sit in a drawer for a few months to come back to with fresh eyes. You finish the guide as much as you can and move on to the next. But technical documentation is a living document. Meaning, you’ll get another chance to make it better when you update it for the next release. How many times do you get to rewrite a story or novel after it’s published? Following pre-determined corporate writing standards and conventions help get it right the first time.

I enjoy reading other writers’ work and try to give an honest, helpful appraisal of the writing. Peer editing has helped me when it comes to editing my narrative fiction, training me to focus on problem areas and to be more objective.

Technical writing in fiction and non-fiction
As I mentioned, you might include information in your novel or story that must be technically accurate. This includes doctor, police, and lawyer stuff. If you include this stuff, make sure you’re a doctor, policeman, or a lawyer. Or you’ve interviewed one or had one review your story for accuracy. Or you've lived with one or are married to one (this is research—take advantage of it). Because if you haven’t done any research, your lack of knowledge will be noticeable on some level, especially to people in the field you’re writing about.

If you’re not writing fiction but another type of book, say a how-to like a cook book or craft book, then you are getting much closer to writing a technical document. You should be using more technical writing elements. These basic elements include:

- Numbered and bulleted lists
- Tables
- Hierarchical headings
- Cross references
- Chunked information
- White Space
- Indexes, glossaries, and tables of contents

These are all important and all help a user find information. My favorite is the list.

Don’t be afraid of the list. The mighty list is your friend. Read through your book. Every time you give the reader a task to perform, put it in a list. This list must start with 1. 1 Open the book. 2 Read every chapter. 3 Break nested tasks and sentences of items into lists. A task shouldn’t be too many steps. If it’s longer than 10 steps, break the task into two or three smaller tasks. Another type of list has bullet points rather than numbers. A bulleted list is a good way to organize stuff. It’s easy to read and helps to break up the monotony of a paragraph of text.

Here’s a rewrite of the last paragraph, using tech writing elements:

How to Use Lists
Don’t be afraid of the list. The list is your friend.

Guidelines:
- Read through your book. Every time you give the reader a task to perform, put it in a list.
- This list must start with 1.

1. Open the book.
2. Read every chapter.
3. Break nested tasks and sentences of items into lists.

Tasks
A task shouldn’t be too many steps. If it’s longer than 10 steps, break the task into two or three smaller tasks.

Bullet points
Another type of list has bullet points rather than numbers. A bulleted list:
• Is a good way to organize stuff
• Is easy to read
• Helps to break up the monotony of a paragraph of text

The idea is to break the information into chunks to facilitate easier reading and to help the reader find the information she needs quickly. Using the above rewrite as an example, say the reader is interested in learning about bullet points, and not tasks and numbered steps. Then, she can skip to the sub-heading Bullet points after finding the main section of How to Use Lists.

Is Technical Writing For You (or, do fiction writers make good technical writers)?
The early 00s was not a good time to be undereducated. Jobs were scarce, even in the Massachusetts high tech industry. I had a film making background, and had spent all of the 1990s working in the wedding video and video duplication business, while also writing short stories and novels. By the end of the 90s, video work was drying up and writing fiction wasn't paying the bills.

I kept reading the classifieds in the Boston Globe and seeing jobs for technical writers. I had no idea what this was, but if being a writer was part of the job description, then I was half-way there. I looked into a few programs in the area, and in 2002 I completed a technical writing program at UMass. It was a big career change. I was starting way over. It took a few years to land a job, but I eventually nabbed an entry-level position at a medium-sized software company and have been employed ever since.

Writing is not a big part of technical writing. It’s maybe 20% of the job (less or more, depending on where you work). It’s more about organization and research and learning what you are writing about. The product I work on is very technical and is constantly changing and improving, so the opportunity to learn about it never flags.

Questions to ask yourself:

Am I logical?
You don’t have to be an engineer to be a technical writer. In fact, being an engineer is a detriment to technical writing. (That’s not to say every software engineer shouldn’t take a technical writing class—she should, so she can better understand how to communicate all that tasty knowledge about the tools she writes code for.) But you will need to be logical in terms of knowing how a subject should be organized, how to approach writing about a subject (start to finish or easiest to hardest), and what information should and should not be included. I am not logical like an engineer is logical—I can’t always get to point F without forgetting or questioning how I managed just to get to point D. But luckily, I don’t have to be an engineer to write.

Am I organized?
You need to be organized. You need to be good with details and time management. But, aren’t most writers pretty good at this already? It helps to skew a little toward the compulsive side here. On the job, you need to pick up details about consistency. This takes practice, and you probably have skills you don’t even know you have. That’s what happened to me. I had no idea I had capacity to notice details, to be organized, and to learn fairly quickly. It took a technical writing program to make me recognize skills I had but was barely using.

Another part of being organized is file management (on your PC or laptop). Go to your C drive. Is it a mess? Are there files and folders in there that you have never seen? Do you have multiple Documents folders? Are you constantly confused about where you saved things? That was me when I first started tech writing. Man, it was rough. For some reason, this type of logic escaped me. But I was forced to learn quickly where and how to save files. There are myriad formats in the software industry, and you will deal with many of them. Don’t be frightened, you’ll learn as you go.

Am I technical?
I’m not technical. But I can learn. And, of course the longer you’re a tech writer, the more generally technical you’ll get. But you’re not expected to be a master at the technology you’re writing about. In fact, often you shouldn’t be. Usually you need to come to a subject as a novice. That way you approach a subject like most of the users you are writing for: fresh and with a lot of questions. But, you have the advantage of working with the people who can answer your questions. Every time you question how or why something works the way it does, you are learning about the product; incorporate this new information and the documentation will be better for it.

That said, some tech writing jobs insist you be technical. A company like Framingham-based Mathworks wants its writers more on the egghead side, with a mathematics background. Some companies that work in the medical field want writers that have medical writing experience. Generally, when you go in for your first tech writing position, you can spin your lack of technical experience with whatever product or technology they deal with into a plus; you need to learn about it so you can better write about it.

One more thing: There are multiple computer platforms. You are used to Windows or Macintosh. But, you might have to work with UNIX systems. UNIX, and all its many flavors (Linux, HP-UX, Solaris, etc.), is an entirely different kind of computer system. One where you type commands into a basic text editor to access files and run programs. It’s not much fun. It’s really basic but powerful, and programmers and developers love to work on UNIX. So, you will eventually run across UNIX systems. Don’t be afraid, just let it happen. Learn a few basic commands, and everything should be fine. Oh, and you’ll never touch a Mac on the job. Unless you work at a fancy start-up where everybody is 25 and they have unlimited cash resources. …oh wait, it’s no longer 1998.

What tools will I use on the job?
You need to know your way around some word processing programs. Master Microsoft Word for a start. Still, when you’re on the job, you’ll need to learn industry-standard programs, like:

• FrameMaker. A powerful word processing program designed for writing books with chapters and an index and glossary, like user’s guides and installation guides.
• Robohelp, AuthorIT, or MadCap Flare. Online help authoring tools. Also, these tools are used more and more as a single-source environment, where you write and store pieces of content that can then be reused in multiple places. Whenever you update the content at its source, the changes are propagated wherever it is used.
• PaintShop Pro or Snagit. Most of the companies I’ve worked for have had basic graphics programs. These are simple programs that allow you to take a screenshot of the user interface (like when you hit print screen on your keyboard and save a copy of what you see on your monitor) and do some minor edits to it, then drop it into your document. I also have Microsoft Visio, which allows me to create simple or complicated flowcharts or logic trees. Also, PowerPoint can be good to create some simple flowcharts as well.

The Technical Writing Life
Technical writing is not a bad gig. You deal with deadlines, egos, myopic and sometimes uncommunicative (but often very nice and willing to share) engineers, and the pressure of getting the software documentation out the door on time. And in a down economy sometimes I feel like the tech writer will be the first to get axed if layoffs hit. But, since first finding steady work as a technical writer in 2005, I haven’t got laid off. I don’t work crazy hours, and only need to put in more than 40 hour weeks during real crunch times before a release. The high tech industry is still in decent shape (depending on where you live, of course); there are still some tech writing jobs out there.

I get up an hour early most work days to write my own stuff. I also take advantage of weekends to write. Having a job where I write is, in the end, a benefit to a fiction writer. It's like having both sides of your brain available for writing, which side you use depends on whether you're writing a user's guide or a novel.