Boston Book Festival -- Recap

As everybody knows, it’s book festival time in New England. So this past Saturday Liz and I attended the inaugural Boston Book Festival. It had been a rainy morning, but we made the trip to Copley Plaza and by the time we arrived, the rain had stopped, and the temps were into the 60s.

First stop was the Boston Public Library Abbey to check out Hank Phillippi Ryan’s Guided Open Mic, sponsored by Grub Street. For 90 minutes, writers took turns reading their original work in front of a room of attendees while Hank took notes.


After each reading, Hank gave a helpful critique of the presentation. She commented on material choice, urging readers to really consider the piece they read in terms of how it represents their work. And delivery, telling one young, eager writer to slow down because she couldn’t make out half her words. She was honest but gentle, doing a great job of making each participant feel comfortable, if not perfectly at ease. Reading in front of an audience is difficult enough, so performing to be critiqued must have been twice as nerve-shattering for these hearty writers.

The line waiting to get into an event at the library:


Next up we took in the exhibits set up in tents outside the library and along Boylston Street. The temps were warm and the rain was still holding off, but there was a wicked wind. Luckily the tents held fast.


There were long lines for Green Mountain Coffee and free ice cream. Thankfully, there were also lines at many of the other booths, including publications like The Paris Review, AGNI, the Boston Globe, and Post Road. There were many publishers represented, including David R. Godine, Etruscan Press, and Drawn & Quarterly, which brought along a beautiful selection of posters, comics, and graphic novels.

It was a good opportunity to discover small presses, and that’s just what I did when I stopped at the One Story tent. One Story is a literary magazine that offers one story per issue, one issue every three weeks. Each issue costs a dollar, and is published as a single-colored booklet. I sort of randomly grabbed two issues, numbers 84 and 93. I liked issue 84’s title, Wedding Pictures. The girl behind the table knew the story, by Donald Petersen, and started to describe it to me as a sale’s pitch. It worked. Issue 93 is titled Meeting Elise, by Nam Le. Subscriptions are $21 for a year.

Then it was time to head across Boylston to the Old South Church Sanctuary to see Tim Kring, creator of Heroes, and novelist Reif Larson, author of The Collected Works of TS Spivet. Larson was first, discussing maps and other signage, and how the meanings of this communication can change depending on context. He presented a series of whimsical and sometimes hilarious slides to illustrate his points. Maps and map making figure prominently into his book as a theme and also as margin illustrations.


Tim Kring discussed the myriad ways in which the TV show Heroes is marketed, er, I mean how it presents the many facets of its storyline. He calls it Transmedia storytelling. The idea is that Heroes the TV show is the epicenter of the Heroes universe. While the show is the main engine, other outlets such as websites and action heroes and comic books can all be developed to extend the story, offering specialized content beyond what viewers see on the show. It’s sort of the ultimate in marketing synergy, where you can buy a toy from the show that includes a piece of character mythology or read a graphic novel about an ancillary character from the show, all adding to the Heroes storytelling experience.

Then Tim showed the trailer he created for a series of books he was shopping around a few years ago. He put together a website which hosted the trailer, and kind of like with Heroes, users could go navigate the website and read all about what his books were about, which includes alternate American history. Must have worked, because he got a book deal.

When that ended we had a little time left and went up to the second floor of the church to check out the Grub Street-sponsored Writer Idol, where a professional actor read the first page or two of anonymously submitted work by writers in the audience. After which a panel of 4 agents explained why each would or would not want to see more of the work. There were a few pieces that the agents agreed they might be interested in. Now it’s up to those writers to get their stuff into the agent’s hands.

Overall, a great experience, even for the few events we attended. The festival was smooshed into one day, so I imagine some attendees might have had a difficult time deciding what to see as there was much overlap in the schedule. But the choices were diverse enough so that if you missed one event, hopefully the next would make up for it. I'll definitely keep an eye out for next year's festival.

If you're interested in Tim Kring's theory of Transmedia, here he is expounding on the subject:

October is Book Festival Time

If it's October in New England, than it's time to get your literati on. This Saturday October 24 marks the first Boston Book Festival, held from 10:00 am - 6:00 pm in and around Copley Square. It's free, man. What could be better? Rain or shine (and the weather's leaning more on the rain side--so bring your rubbers). There will be 90 authors and presenters, events, a street fair, music, contests, exhibitions, and book signings.

The line up of authors is damn impressive: John Hodgeman, Elinor Lipman, Anita Diamant, Chris Castellani, Robert Pinsky, Orhan Pamuk (keynote speaker), Ken Burns, Anita Shreve, Iyeoka Ivie Okoawo, Alicia Silverstone (huh?), Richard Russo, Stephen Carter, Andre Dubus III, Ben Mezrich, Tom Perrotta, and many more. Check out the schedule for event times and locations.

At least one event ain't free: Boston Noir Launch. 6-9 at Boston Public Library Rabb Lecture Hall. $15 per ticket, and still available as of this post. "Celebrate the launch of the new fiction collection Boston Noir (Akashic Books) with contributing author and master of the art of noir, editor Dennis Lehane. From Dorchester to Southie and from Beacon Hill to Brookline, Boston Noir features 11 Boston neighborhoods and nearby communities in stories by contributors including Brendan DuBois, Dana Cameron, Jim Fusilli, Lynne Heitman and Russ Aborn, who will attend the launch event. Expect a dynamic, drama-filled presentation." Okay.

Things actually get underway Friday night at Trinity Church where "Robin Young, the host of Here and Now on WBUR, will emcee the evening’s festivities, beginning with Boston Mayor Thomas Menino’s reading of a passage from his favorite book." Then, Livingston Taylor performs and discusses songwriting.

Grub Street is a partner, and as such they are offering some free workshops, including:

- Jumpstart Your Writing (writing exercises with mini-lessons on craft) taught by Grub instructors Stace Budzko and Grace Talusan
- Writer Idol (a chance to get the first page of your book heard and critiqued by a literary agent or editor), judged by agents Esmond Harmsworth, Janet Silver and Eve Bridburg, and editor Helene Atwan
- Guided Open Mic with Hank Phillippi Ryan (a traditional open mic with lessons on how to perform your work). I attended this session when Hank offered it at this year's Muse and the Marketplace. If you ever read your writing in public, this event is a great primer for how to do it right, without putting your audience to sleep.

Wait, that's not all. Starting this Thursday, October 22, and running until November 8, it's the return of the Concord Festival of Books. 18 days, over 40 authors, 22 events. Most events are free. So, unlike the Boston Book Festival which delivers the goods in one day, the Concord festival spreads the love out over two and a half weeks. There will be discussions, readings, and talks. For example, on Monday, October 26th you can catch Larry Tye talking about Satchel: The life and times of an American legend, and Dick Lehr discussing The Fence: A police cover-up along Boston's racial divide. Other authors include Howard Dean (opening day speaker), Chris Bohjalian, Gregory Maguire, Katherine Howe, Jessica Shattuck, Fred Marchant, Mitchell Zuckoff, and lots more.

While this is a Concord, MA-based festival, as in years past some events are held in Lowell, at locations like the Pollard Library, Comley-Lane Theater at UMass, and Wannalancit Mills. A couple years ago Liz and I went to see John Elder Robison and his brother, Augusten Burroughs, speak at UMass as part of the festival. It was a great evening, where the audience heard touching, enlightening, a little horrific, but mostly hilarious stories about Robison's experiences understanding and accepting his Asperger’s Syndrome. Here's Liz getting her book signed afterwards by Augusten:


A big shout out to Rob Mitchell, an all-around great guy who founded the festival in 1993 and still directs the whole she-bang.

Unlike a writer's conference, these book festivals are geared more toward readers and book buyers than to writers. Attending a book festival as a writer, it'll be a relief not to have to worry about getting a manuscript critique or running into an agent I might have had an awkward interaction with last year (I suppose that could still happen...).

I wish the Boston Book Festival a great inaugural event, while also anticipating another successful year for the Concord (and Lowell) Festival of Books.

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.

Technical Writing Vs. Narrative Fiction, Part 3

Editing

At most companies today, a technical writer also acts as a technical editor. Back in the day (the mid-80s, which I hear about a lot in the software industry) technical writers were only expected to write. Technical writing departments often had their own editors and illustrators or graphic designers.

That is almost never the case anymore. Desktop publishing has given writers all the tools they need to produce a document. Graphics programs (for example, Adobe Photoshop or InDesign) are so prevalent that a tech writer is expected to be her own graphic designer. And most technical editors are probably now technical writers or educators.

For example, in my last job there were about 200 technical writers for a company of approximately 16,000 employees. There were about 4 or 5 technical editors who were also educators and trainers. They didn’t have much time to edit. When I left the company these technical editors had been absorbed into the technical writing organization proper, and no longer did any editing.

Editing is arguably the most important part of any writing project, fiction or non. I’ve broken editing down into four sub-categories:

• Structure
• Pacing
• Consistency
• Standards

Structure
Narrative fiction and technical writing both need a consistent, meaningful structure. Structure is borne of logic.

In tech writing you need to know your structure before you start writing. Structure is dependant on your main intended audience (the user), the “story” you are telling (how users accomplish a task), and the level and order of the information needed to tell a complete story. Often, after you’ve planned and researched a subject, you use an outline and/or table of contents to figure out the structure. Remember I talked about two ways to tell the story of a user’s guide: From easiest to most difficult or from start to finish. This story helps dictates your structure. It can change as you go (the configuration chapter should go after the installation chapter—who knew?), but your research and planning takes care of most structure questions beforehand.

Narrative fiction is a different animal. You might be saying (if you haven’t attempted a novel), well damn Unreliable Narrator; the structure of a novel is however you write your story. Structure? Follow your muse.

Following your muse alone might work for a couple of months or years. You finish a couple drafts, fix your typos, dot your i’s, cross those t’s, and then you send it out to a bunch of agents and forget about it for a while. Why? because you are done! Congratulations. In the following months you receive (if you’re lucky) a slew of rejections. Form letters or emails saying Not right for us or Not accepting new clients at this time. Fancy letterheads lose their impact when nobody signs the letter. Maybe you get one or two handwritten notes (but probably not) saying thanks but no thanks. What the hell went wrong? With all those novels getting published every week, where’s the love for your opus?

Chances are you’ve got some problems with your novel’s structure. Structure problems can be tough to spot. You need other eyes reading your manuscript. It doesn’t matter how closely you adhere to an outline or an overarching vision—your novel must strike a delicate balance, reflected in its structure. A novel’s structure can mean things like how to present multiple characters. Or when to reveal important information. Or weaving in a character’s back story or other important events that happened ten years earlier, but somehow affect all the characters now.

For example, say you decide to tell your story from the points of view of four characters, and you give each chapter over to a character’s third person view. The problem is, not all these characters are main characters. Two of them are main characters, and the other two, not so much. So, you can’t give the minor characters equal time, you have to strike that perfect balance, giving the main characters more air time or else the reader will wonder who the story is about, who they should root for and empathize with. But, you already wrote the book, and sent it out, before one of your readers pointed this out to you.

Structure problems for both tech writing and for narrative fiction can be fixed. For tech writing it’s usually a matter of cut and paste. Or adding and subtracting. Sometimes it works the same way for narrative fiction. But novels are much more delicate. Pasting a paragraph from chapter 2 into chapter 10 will probably have repercussions, ripple effects. But don’t be afraid to tear up your structure and rebuild it. It might take some time, another draft or two, but if it makes a better novel, you have to consider invasive surgery.

Pacing
This is closely related to structure, especially for narrative fiction. In tech writing the structure, story, and the main audience of the document dictates the pacing. You don’t want a user/reader to fall asleep reading your guide/online help, but you also have to give all pertinent information. Pacing for tech writing involves being concise and striking the right balance of information.

Writing concisely is tech writing 101. Don’t use ten words if you can use four. On the other hand, don’t leave out conjunctions just to save space. Just the facts. But not too many. Again, much of this is dictated by your audience. Are they new users that need more context and overview information? Then you’ll have to include an overview chapter with concept material. That’s tough reading, a slog if you will, so you want to write clean and tell your story with just the right words. Also, your company or your documentation group will have standards in place to follow. You don’t have to reinvent the user guide every time you write one. Good pacing in a tech document strikes a balance between giving the user the information she needs and keeping her from slamming the book closed in disgust because you gave her either information overload or not enough information.

Pacing in narrative fiction is closely related to structure. Let’s go back to my example: four characters spread throughout all your chapters. You don’t want to give one of the more minor characters the same number of chapters as the main character because this throws off the pacing. The reader might slog through minor-character chapters just to get back to a main character chapter. Give the main characters three chapters (for example) to every minor characters’ one chapter.

Pacing also comes into play at the beginnings and endings of novels. Where does your story begin? On page 1, hopefully. Maybe. Sometimes not. Sometimes your story doesn’t start until page 40, when your main character first steps into the crack house. So what about the first 39 pages? Read them again. You were finding your character, and anything important can be woven into the story after page 40; which is now your new page 1.

So your hero kicks drugs, joins the local police force, and eventually goes back to that crack house with his squad to bust the nefarious drug dealer. Ah man, great scene, full of action and pathos and irony and it’s obvious you’ve done your research. And the story is about to end, right? Wrong. You drag it out for another 75 pages. And the reader is stuck wondering what they’re reading. Did you introduce a love interest on page 350? Is she a new main character? How about the cop’s best buddy, a retired cop who’s now hanging around the station giving sage advice. Don’t end your book too many times. Know when to get out. Give the reader what you’ve set up in the first 90 thousand pages, and don’t give them another 15 to gnaw on. As with tech writing, you don’t want to give your reader unnecessary information that clouds the story.

Consistency
In your novel, if a main character drives a Prius on page 3, he better drive a Prius on page 303, unless he sold it and bought a Humvee. If your main character is the type of guy who seethes with anger because he hates his job, then by the end of the novel he better have:

• Quit the job to follow his bliss
• Shot his co-workers because they were making his life a living hell
• Met and married a woman who showed him how great love and life is, making his day-today job more bearable
• Get very close to one or all of the above, but in the end doesn’t change

If you don’t follow through with all the emotions and situations you introduce, then you’ve got a consistency problem. If you think no reader noticed that offhand reference to bestiality in chapter two (you thought it would give your antagonist shading), you’re dead wrong. Readers notice the smallest details, even if they don’t know they’ve read them. After they finish the book and say, “Hey, not a bad little literary novel,” three or four weeks later they’ll start remembering odd bits and pieces that don't fit, including how you never followed through on that bestiality thing. It can be even more amorphous than that: they know something is wrong with the story but can’t explain what. Readers know a bad piece of writing, even if they can’t tell you why.

The same goes for technical writing, except in a more crucial way. Everything about a technical document must be consistent. Everything from the terminology you use to the minutia of spelling and structure. You must present a feature or concept the same all the way through. And not just in one document, but throughout a company’s literature. From online help, to a user guide, main corporate website, and marketing material. This can be a huge, odious, and time consuming job. And terminology is constantly changing as products continue to be modified and integrated. Consistency is really the heart of technical writing.

One of the most important jobs of a technical writer is to set the user at ease. Introduce the conventions of the guide in the preface, introduction, or first chapter, so that as the reader moves through the document, she knows what to expect. Unlike narrative fiction where a writer can turn all lyrical and subjective, or screw around with time or point of view, a technical document must lead the user through the logical progression of tasks with tact, clarity, and consistency.

If you use the term failover a certain way in chapter one, you must use it the same way throughout not just this guide, but in the online help, and in the marketing material. And you better describe failover the way it actually acts in the product: Your documentation must mimic what the user sees when she uses the product. Consistency is in the details. Cross references to other material (“See page 12 for more information.”) better be accurate, or users will get frustrated and stop turning to page 12 for more information.

Consistency must be maintained at all levels, even those a user may not even notice. But, like with a novel, they will be able to tell that something is not right. Even if they can’t put their finger on it. If you start the first procedure with an introductory sentence, then start all procedures with an introductory sentence. If you don’t, the user will wonder where the damn introductory sentence is, and say, “Maybe this procedure is in some way different from that other procedure; maybe it’s not as important. That’s it! I don’t have to follow this procedure because there is no introductory sentence.”

When you first tell a user to click Tools > Insert > Table, you are introducing a couple of conventions. What are they? Can you spot them? Bold. Whenever a user needs to click a button or other item on a user interface (like the one in which you are reading this blog) then it should be presented in bold text. What else? The > between items to click. This means the user is to click these items as a series of steps to insert a table. I used as few words as possible and I have the user trained for the rest of the user’s guide.

If you screw this up, the user will lose confidence in the guide. Will be more likely to contact technical support rather than touch another technical document from your company. Ever. Ever again. You’ve lost them. Forever. Introduce conventions and standards and use them consistently.

Noticing consistency in my technical documentation has helped me appreciate and discover it in my narrative fiction. Most of the editing techniques I’ve picked up on the job have come in handy when planning, executing, and editing my novels, stories, and outlines.

Standards
Predefined standards give a technical document much of its consistency. By standards I mean a set of rules you follow to give a company’s technical documentation a similar look and feel. It includes things like font type, how to format a numbered list, and putting a preface and index in every document.

Fiction writers define their own standards. They might pick them up from an aesthetic they learned in school. Or from certain writers that they read and emulate. Standards in narrative fiction have less to do with typeface and kerning than with how to use the rules of grammar, and breaking them or incorporating them when the story calls for it. Do you place a character tag before or after a line of dialog? Do you place description in the same paragraph as a line of dialogue or in a separate paragraph?

For my novel, "A Little Disappeared," I set a standard over the first two chapters for the reader to follow. The first chapter introduces my main character, Keith. Keith is 38 and his wife has left him. He has embarked on a cross country trek to find her. This storyline takes place in a contemporary setting and is told from the first person. Chapter 2 introduces the same character when he is 14 and is told in third person point of view. I follow this standard throughout the novel. If I’ve done my job correctly, the reader should be able to read the story and accept, or at least understand, this structure as a standard I’ve introduced early on. (Hopefully they’ll accept it, because it’s harder and much more expensive to get in touch with narrative fiction support than technical support.)

Whether you’re a tech writer or a novelist, you train your readers (usually in the first chapter) how to read your writing, creating a trust. If you break this trust with inconsistencies, then readers will be wary on some level of the story you are telling them.

These are just a few examples of where technical and fiction editing crossover. I tried to cover the most important ones. If you can think of others, let me know.

Tune in next time for the 4th and final post in this series when I’ll discuss:
- Technical reviews
- Peer editing
- Technical writing in fiction and non-fiction
- Is Technical Writing For You (or, do fiction writers make good technical writers)?

Technical Writing Vs. Narrative Fiction, Part 2

Telling a Story

Chapter 3 – Configuring Disaster Recovery for Zombies

Disaster recovery is a system configuration that helps ensure your network environment remains secure and online in the case of a physical catastrophe; for example:

• Earthquakes
• Hurricanes
• Zombies

How Disaster Recovery Works
When the primary system on which the software is installed goes offline (when zombies chew through the wires or set the building on fire), failover is initiated, and the secondary system is automatically brought online at another location (Alaska, where there are no zombies…yet!) and continues to function with a minimum of downtime.

This chapter describes the procedures necessary to configure disaster recovery in your infrastructure and fend for your life from flesh-eating zombies, including:

• Installing the software
• Killing zombies: guidelines and best practices
• Configuring disaster recovery

To install the software
1. Log on to the server system as the administrator.
2. Navigate to the closest exit.
3. Double-click……Zombies!

A software user's guide tells a story (sans zombies). A novel tells a story (about anything, including zombies). It could be argued (I double dare you) that any book, technical or otherwise, has to tell a story. What kind of story does a software user guide tell? Well, in the planning phase of my disaster recovery user guide (my example from Part 1 all the way through here) I have to determine who my audience is so I have a better understanding of what they need to know about disaster recovery. Is the user very technical? If not, I will need to include more introductory and concept material. Is the user a network administrator? If so, my user won’t need a lot of setup, she will just need the procedures to configure her software for disaster recovery.

Where’s the story in that? Well, look at the outline. Chapter 1: Introduction. Chapter 2: Install and Configure software. That’s for the new user. The experienced user does not need as much intro material, so that will not be part of the story. What is the motivation? Why tell this story? My audience, new or experienced, needs to install and configure the software correctly. I have to tell the story of this install and configuration.

During my planning phase, I’ll determine how I will tell the story. There are two ways I can go:

• Start with the easiest information and then, continuing through each chapter, get more and more detailed, more technical. This might be the way I write one user guide for both those audiences (new and experienced). The new user will get all she needs in the first few chapters and then can stop reading. The experienced user might skip the early chapters, and get to the nitty gritty of the story: the procedures she needs to configure the software for every disaster recovery scenario (there is more than one type of failover—but I digress).

• Tell a story from start to finish, logically, like documenting each point of a flowchart. Maybe every user needs all the information, so chapter 1 begins my story from where any user needs to start the process. Chapter 2 continues it, and so on, through to the last chapter. You can look at the table of contents of my user guide and consider each chapter as one process in a complete series of necessary processes (Chapter 1=Process 1, Chapter 2=Process 2), with each chapter/process broken into all the procedures needed to complete the process.

No one, and I mean absolutely no one, reads a technical document for fun. (Unless you’re a technical writer studying bad tech writing to figure out what not to do.) But many people, whether they’re an engineer (learning a new product or reviewing technical documentation because they’re the only person in the world who knows how a piece of the software puzzle works because they wrote the code) or a soccer mom (installing the latest version of iTunes) will at some point have to read a user guide or some online help topics. The more concisely you present and tell the story, the better experience any user will have with her product. Often a user clicks that Help button because she can’t do something. She needs information fast; she’s pissed off, and she’d rather not call tech support. This is when telling that story about the installation and configuration saves the day.

It should go without saying that narrative fiction also tells a story. I mean, that’s why it’s narrative; it tells a story, somehow, from start to finish. But how are these two types of storytelling similar? Okay, you’re in a book store and you pick up a copy of the new hardcover by that hot young author who looks good in heels and has a haircut you envy. You’ve heard good things, read decent to excellent reviews, and you need to find out for yourself. You read the first paragraph. It doesn’t grab you. You read two pages; you’re still not sold. One more page, and the hot young author has lost you. You put the book down, walk away, and buy a new book by a writer whose ten other books sit happily read on your bedroom bookshelf (yes, I have a bookshelf in my bedroom).

What the hell just happened? This reader clicked Help and tried to determine what the story was. And she either had no idea what the author was trying to say, or it wasn’t for her. She may or may not know why. I’ll argue that a reader of a user guide can get the same feeling—this book sucks, but why? In both cases, the story failed. For the fiction reader (reader A) the author failed at storytelling. But, we can assume that if it didn’t work for reader A, there’s a reader B and C for whom it didn’t work equally well. She is not alone.

Novels and user’s guides must tell a story clearly, concisely, and with a minimum of bullshit, or readers will give up out of frustration. Which brings us to the most important part of this comparison: Editing.

Tune in next time when I’ll discuss the following parts of editing:
• Structure
• Pacing
• Consistency
• Standards

Technical Writing Vs. Narrative Fiction, Part 1

I work as a technical writer for a software company. I spend way more time per week writing technical documentation than I do writing fiction or coming up with blog posts. When I tell most people I’m a technical writer, they look at me quizzically, canting their head like a dog agitated by a high pitch. I explain that a tech writer creates technical documents like software user’s guides, installation guides, and online help. The general public uses this type of documentation all the time. Whenever you are on your PC or laptop using a program (such as Microsoft Word) and click that Help icon, the help system and all the accompanying topics that display were written (hopefully) by a tech writer.

After juggling both technical writing and narrative fiction, I’ve found that there are some similarities between the two types of writing. Especially after being asked questions like, “Does the tech writing take away from the novels?” or “Is it hard to switch gears between the two?” The two types are different for lots of reasons, but that doesn’t mean that a strength used in technical writing can’t cross over and be used in a novel. And vice versa.

Starting with this post (and running for the next two or three) I’ll compare and contrast elements of both technical writing and narrative prose, highlighting where they overlap. Elements include:

- Planning
- Research
- Telling a story
- Editing
- Structure
- Consistency
- Technical and Peer Reviews

I’ll conclude by discussing whether technical writing is a good career for a fiction writer and ask questions to help you figure out if you would make a good technical writer.

Let’s take a look, shall we?

Planning
Tech writing is all about the planning. It works like this: the release schedule of a software product (for example, software that monitors your network and lets you know when connections are failing) is generally very short. Maybe a year. More if you're lucky. That means, as a writer, you have to figure out how to write about a new feature that is part of the software release.

In other words, let’s say this network monitoring software will now have the functionality to work even when there is a physical on-site disaster (for example, an earthquake or hurricane). This new feature is called disaster recovery. I have to monitor the progress of this feature’s development, learn about it, determine who the audience is (who the users are), and then, when development has finished writing the code (you know, C ++ or Java or whatever those guys do) use it to make sure it works like they tell me it's supposed to. Before I start writing, I have to figure out what needs to be documented and, sometimes, how long it will take. In most cases I’ll write an outline, sort of like a table of contents that will highlight what I plan to cover in each chapter.

I talk a lot about outlines on this blog. I’m no stranger to outlines for either tech writing or for novels. I worked on novel outlines before I became a tech writer, but I think my novel outlines have benefited from having to outline and plan all my technical documentation. I feel I now better determine what scenes must go in my novel to move the story along, what scenes I could write but would probably get cut later, which scenes are necessary to include to understand character motivation, and (if I choose to include them in the outline), which scenes end the story.

Before I start writing a novel, I often write a truncated outline so I can figure out the best way to start the book to lead me in the right direction to tell the story I want. I may have no idea what will happen in later scenes, even though I can picture some overarching idea about how the story ends and how to get there. With technical documentation, you have to map out all parts of the document before you start writing, to ensure you are telling the right story for the right user (more about telling a story later). Planning is an aptitude that serves me whether writing on the job or off.

Research
It doesn’t matter if your novel takes place in a small Florida town and you want to know what the local sheriff does all day or you're writing about a graphical user interface—you need to do some research after you decide what subject to write about.

You can start your research online. Yes, I Google and Wikipedia at work. You have to be careful, but public search engines and wikis are not a bad place to start. Of course, nothing compares to interviewing a subject matter expert. Or getting firsthand experience. Or both.

Go to Florida. Go to that small town you saw on Google street view. Interview that sheriff. Walk around that small town. I guarantee you’ll garner much more data than you thought was there in the first place. Firsthand experience is imperative. If you can't get firsthand experience with a subject, then talk to somebody who can.

As a tech writer, when I’m faced with writing about a feature or technology I know nothing about, I try to do as much research online as I can. That means seeing if there is generally available information about the topic. Yes, disaster recovery is a recognized industry term. I can find overviews and learn concepts very quickly. Then I go to my company’s internal online resources. This may include an intranet or wiki page where the engineers I work with have posted information about the technology and, hopefully, detailed information about how they are implementing the feature/technology with our product. From this information I start really solidifying the outline/Table of Contents.

After I understand, more or less, what’s going on, I sit down with a subject matter expert (my sheriff) and ask informed questions. I need to know enough to understand at least some of what my subject matter expert tells me. Same goes for interviewing somebody for a novel. You should know going in what questions you want to ask, at least enough to get the conversation going into the direction you hope it takes. You should come away with lots of notes or a full audio tape, and ideas about how to make your story or documentation better. And don't forget to thank the sheriff, and make sure it's okay to contact him later to ask follow-up questions.

Next time: Telling a Story

Kerouac & Lowell

Lowell, Massachusetts is the birth (and resting) place of Jack Kerouac. And since Jack died in October of 1969, October is Kerouac month here in Lowell. And this year marks the 40th anniversary of his death. This weekend we're in the middle of Lowell Celebrates Kerouac. It started Thursday, but if you hurry on down this rainy Saturday you can still catch events like readings from Dr. Sax at Kerouac Park.


If you can't make that, then get downtown by 4 for The Kerouac Places of Downtown Lowell tour. This starts at the Lowell National Historical Park Visitors Center at 246 Market Street (around the corner from Unreliable Narrator's historic condo building). If you don't want to take a walking tour of Lowell in the rain, then find out how you can do it on your own time here.

If that's not your style (plus, it's raining), then check out an open mike starting at 5:30 at Brew’d Awakening, 61 Market Street. Here anybody can read a selection of their favorite Kerouac writing. Or, if you're a writer and Kerouac acolyte, then you can read your own Kerouac-inspired writing.

If you can't get to Lowell until tomorrow, then your best bet is to show up by 11:30 a.m. at Caffé Paradiso on Palmer Street, for a screening of Grave Concerns—A Deadly Road Trip, a documentary filmed during the On the Road scroll exhibit. Despite this gruesome and questionable title, it sounds like an interesting and apt addition to this festival.

Here's the trailer for Grave Concerns:

Two summers ago when the On The Road scroll exhibit hit the Boott Cotton Mills Museum in Lowell, Liz and I attended the opening night festivities.



Here's the scroll. I took this picture before I found out that I wasn't supposed to photograph it, especially with a flash. The flash didn't cause any additional damage, although I did spill some coffee on it: