Whispers from the Myth Teller

For the record, I am *not* a fucking typesetter. My job is more than just copying text from one source, pasting it into another, and making it *pretty*. When I am documenting a new feature, I pull the information from multiple sources, rewrite and restructure that information, draw up the illustrations, and I test every single procedure to make sure it works the way it's supposed to.

Unfortunately, this tends to reveal flaws in the code that people would rather no one see. So when I start barking up the trees, trying to get answers, the frightened little engineers either scurry away or they try to dismiss my concerns by saying "Don't you worry about it. Nobody reads that section anyways." *twitch*

I haven't been here long enough to be able to rumble the earth by putting my foot down, but that day is coming, let me tell you.

A couple of years ago, I was speaking with a fellow techwriter who had attended a conference on software design. She attended a lecture by an American software company that had embraced a radical development process.

Most IT companies follow the waterfall development process which basically means you start with a set of requirements, come up with a basic design (which is usually quite vague because it is rushed), write the code for that design, test the code, fix the bugs, and release it.

Somewhere in that process (between the writing of code and fixing of the bugs), the documentation process starts. Because the writer comes online in the middle of the process, the writer is always playing catch-up. He'll write sections of the User Guide, the code will change due to bug fixes, which in turn affects the documentation in terms of procedures and/or screen grabs. MOST sections of a User Guide will be rewritten, rewritten, and rewritten.

All the while, the release date looms in the distance and everyone scrambles to get their stuff ready so that the application will release on time. Usually, this date is selected in terms of its proximity to financial quarters or trade shows, rather than being selected in terms of when the application is ready.

So this American software company reported that, when they tried to follow the waterfall process, they would regularly blow their release dates, break the budget, and work their people excessively. Something had to change, so they flipped the process on its head.

The Product Designers went to the Documentation team and had them write the User Guide for the product BEFORE the code was written. This User Guide would become the extremely detailed specification that the programmers would then follow to write the code. You want to know how the program is supposed to work? RTFM.

When the company followed this plan, they stayed on budget and released a stable product on time. To be sure, it lengthens the planning stage, but at least the programmers have a very well-defined document on how the products works to reference.

Even with this plan, the Doc team is still busy once the coding starts. Bugs come in and some procedures/screen grabs will change, but these changes need to be justified and the writer is much more involved in the development process. No more cowboy coding, which ultimately leads to broken code, inaccurate documents, and extending testing times.

Speaking from the writer's point of you, I can tell you that I like the thought of being DRUNK WITH POWER (*cough*), but this process does produce solid results. And it also elevates the role of the technical writer in the development process, which I can tell you is currently somewhere between the last rung on the priority ladder and oblivion.

The ironic thing in the IT business is, with all the obsession with new technologies and new ideas, the thing that scares IT culture the most is change at the development level.

Tonight is the Winter Solstice, the longest night of the year. Many people I know will be lighting candles and holding all night vigils to welcome the return of the sun after being away for so long. That might sound a bit weird, but how many of you have a dead pine tree in your home covered in lights and shiny tinsel. When you take a step back, Xmas has some weird traditions around it.

Looking back, it's been a transformative year. I've been going through my own metamorphosis in terms of my career path (moving from technical writing to biography writing), but there are a few others I know who are struggling with their own demons right now. All of life's challenges seem to be building to a surging point and these people are trying to decide if they can ride the avalanche or be swept away by it.

For my part, technical writing is a lucrative career path but it's starting to get soul-crunching. I'm hoping the biographies will be just as lucrative, but also more satisfying. It's difficult to get excited about your work when you write technical manuals that, by their very nature, have a reputation of being unhelpful and uninteresting. Of course, MY technical manuals are helpful and well-designed, but I work in an industry that does not value good documentation.

However, the biography is something that people can value, not only when they first get it, but also over time. I feel good about the product and I think it's something that can really respond to a need for people searching for personal history and family roots. But I still need to pay the bills, so I worry about the realities of money and providing for my family.

I strongly believe in this project, but the future is fraught with peril. What makes it easier is having a strong support from friends and family; if they believe in me and my project, I can't be too far off-base, can I? Maybe I need to put some trust in them too...

So to those people who are struggling with their own perils, I can only advise them to lean on their friends and family (both biological and selected). We're dying to help you, if you'll let us.

So let's raise a glass to each other, count our blessings, and carry each other into a new year. It's going to rock.

Stated in a meeting with the head of development, the tech pubs writer (moi), and the head of marketing:

HoM: So why are we late in delivering this product?

HoD: Part of the problem is because the developers didn't return the review copies of the documentation back to the writer by his deadline.

HoM: Well that's not surprising since just the User's Guide is over 400 pages long! (looks at me meaningfully) We're going to have to find a way to make the user docs shorter so that we can keep to our schedule! (laughs)

Moi (inner monologue): Well maybe if you produced a product that wasn't so convoluted in its design, it wouldn't require over 450 pages to explain it.

I am the King of Discretion. I also trained at the toughlovemuse School of Repressing Your First Impulse. It's really paying off.

On Saturday, I dropped off the Second Draft of my first biography project. I met up with my client at a bakery, put the leather-bound book in his hand, and he swooned.

Whew. First hurdle met. The client was impressed and happy. I was glowing about that for hours afterwards.

But the real hurdle was the birthday supper. The subject and true recipient of the biography was to receive it on Sunday night during a birthday supper. Up to this point, he had no idea this was being put together. His reaction would determine whether this project was a success or not.

I spoke with my client this morning. Here's what he told me:

First there was confusion.
Then there was stunned silence.
Then there was stunned sputtering.
Then there was open weeping.

When he realized what the biography was, he was floored. He couldn't believe it.

Now he won't read it. Because it's a Second Draft, he wants to wait until it's done before he reads it. I'm going to get a final interview with him and just ask him questions based on each chapter in the book (family memories, political life, work life, etc.). Then I'm going to interview the sons and have each of them give his thoughts on his Dad. That will all go into the final chapter.

And then Gilles Vigneault has promised to write the Preface (he is an old friend of the subject of the biography). We need to get the family tree and more photos, but now we'll have more access to the family slides since we don't need to keep it secret.

The plan is to get the Final Draft done before the end of the month. But I am still glowing in my early success. Go me!

Over the past few months, I've been writing and developing a User Guide for a product for my client. I've dropped Drafts to people and set deadlines for the comments to be returned to me. Some people are pretty good about getting the comments back to me on time, but others just shrug their shoulders and say "I didn't have time read your documentation. I've got better things to do."

Now I'm a week away from the end of the contract and people are calling for my head. All these people who said they didn't have time to read are now reading and not liking.

NOW they don't like the structure.
NOW they're telling me the content needs to be improved.
NOW they're reporting that the documentation is not a quality product.

NOW. A week before the end. Not two months ago when I put out the Second Draft. Not a month ago when I put out another Second Draft for more people to look at.

They tell me this NOW, a week before the product is to be shipped out. One guy had the audacity, after admitting that he had NEVER read the document (despite many requests to read the documentation before this), to ask if this was a final draft. Argh!

I need to get out of this business.

Dear Programmer,

When I ask you to provide a definition for a component in the application, don't tell me that I don't need that information. I'm the writer, so I know what I need to include in my documentation. You're a coding monkey, so stick to what you're good at.

Please don't provide information that tells me how stupid you think I am. If I need a definition for an object call LargeRedBall, I need something a bit more substantial than a definition like "LargeRedBall is a large ball object of type red." That's not helpful. I need to know what it is using terms that are not used in the name of the thing and I need an example of its use.

Also, don't sigh and act like you're doing me a huge favour giving me this information. I'm not a technical writer because I'm too stupid to be a programmer.

Sincerely yours,

Hobbes
The Brittle Technical Writer

I'm a writer. I know how to take criticism. I know how to remain professional when given an edit of my work.

However, am I experiencing unreasonable amounts of anger when one of my reviewers, upon finding a danging modifier in my document, tells me to check out a website about grammar? When I find a bug in the software, am I supposed to pull a book on C++ from the bookshelf and thrust it at the programmer?

It was a First Draft people! I was given two weeks (in addition to all the other documents I was working on) to put this together quickly just to get a feel for how it would look.

So yes, there are a few problems with the writing that would've been corrected with a grammatical edit by the other writer.

They also accused me of being too wordy. A tutorial has to do more than just give you the steps to reach a goal; it also has to point out stuff along the way so that you understand the concepts being taught to you.

But what do I know? Everyone believes they can do my job better than I can.

*gnashing teeth*

There's something unsettling about watching a backhoe truck leading a convoy of limos through a cemetary. I know it's ashes to ashes, dust to dust and all, but does it need to be so industrial?

My thoughts are just everywhere and nowhere today.

Yesterday, I started on my first day at my new job. I've never really worked in this industry before, so I have lots to learn and lots more mistakes to make. I think one of the hardest things about this new job is the fact that I have to stand on my feet for most of the day.

Give up? Don't know where I'm working? Drum roll please...

I'm working behind the counter at Melange Magique (for those who don't know, Melange is a local (Montreal) pagan shop). I've had many friends work there and I've been associated with the shop for about 5 years now since I started volunteering at the Montreal Pagan Resource Centre.

It's a temporary position, but I'll be there every day for the next two weeks. I've never worked in retail before (or worked a cash register), so it's a real challenge. I've always had ideas of opening my own cafe someday, so working in a retail shop will give me some idea of what this type of business is like.

It's also putting a real dent in my days, where I usually spend that time doing research and company development for Documentia, so it'll mean later nights as I spend time catching up.

Come visit me if you have a chance!