Why you really should plan projects

All of the reasons for planning in the preceding post are summed up neatly by Magid’s Law:

“It doesn’t matter how you get there if you don’t know where you’re going.”– Paul Magid

Paul Magid is one of the Flying Karamazov Brothers and coined this profound bit of wisdom 30 years ago. It’s the best justification for planning I’ve ever heard.

That’s all I need to say about this.


Why you should create a documentation plan

There are a lot of good reasons to create a documentation plan. The first and most important is that the documentation plan states the projects goals. The documentation plan also specifies the project details and describes the process for accomplishing the project.

A documentation plan answers the following general questions:

  • What do you want to write?
  • Why do you want to write it?
  • How do you want to write it?
  • Where will the document be written and produced?
  • Who will do the work?
  • When will they do it?

You’ll recognize this immediately as the 5 W’s and H.


Writing effective documentation plans

On my first technical writing job in 1984, Linda Jaech, my first doc manager (and a damn good one!) taught me how to do a documentation plan. It was a profound part of my education as a writer; thinking about it, it may have been the single most important thing I ever learned about technical writing.

We printed our documentation plans back then on a Diablo 630 daisywheel printer (a name which will make all the old-timers who read this nod their heads and go “Uh-huh!”). I used the format for the projects I did at that company, then for contract assignments, and then when I was doing my first book proposals. (I’d print those out at home on my Juki daisywheel, a noisy little printer that was nevertheless very, very good. And it worked exactly like a Diablo 630.)

Over the years, I’ve updated the format, but apart from the addition of some items and sections and the vastly improved formatting available with a laser printer, it hasn’t changed much. I still have a printed copy of the documentation plan my first Microsoft manual from 1986 and, apart from the limited formatting you can do on a daisy wheel printer, it’s clearly the same format. I’ve used this format for well over 100 manuals and writing projects and maybe 40 book proposals, a couple of dozen of which have been published. The format is adaptable and easy to use. I think that’s pretty cool.

This series of posts is going to show you:

  • why you should plan
  • the sections in a documentation plan
  • an analysis of the individual sections
  • where to get a copy of my blank documentation plan template

You’ve Had an Accident. Now What?

Before I get into the series on documentation plans, I thought I’d post something totally different that a friend requested I post. I wrote this after dealing with a rather serious auto accident in 1993 that finally got resolved in 1997 and even required me to sue my own insurance company. When I began the process, I didn’t think that that was a good idea, but after I got jerked around egregiously by the company I’d been paying premiums to for a couple decades, my reluctance evaporated like spit on a hot griddle.

——–

Someone pulled out from a stop sign too early and broadsided you at 30mph. You’re definitely banged up. What do you do now? This article will describe what you should do from the minute the accident occurs to make your life easier and to minimize problems getting suitable compensation from the insurance company.

  • Call the police and don’t move.
    Get the police there as soon as possible. Don’t depend on others to call them. If you’re injured or trapped, say so and request immediate medical attention. Until the police or emergency services arrives, don’t get out of the car unless your car is on fire or likely to be hit again, even if you don’t think you were injured! If you’re suffered a serious trauma, you can compound the injury (sometimes fatally!) by moving around without a cervical collar or back support. Furthermore, getting out of the car may actually increase your chances of getting hit by a passing car.
  • Be careful about saying too much.
    You’re required to speak to the officer at the scene if s/he asks you about the accident. Before you say anything, breathe deeply and think. Describe the accident as completely as you can. If you’re simply too rattled to give a description, say so. Request a copy of your statement. Get the officer’s name and badge number for your records. You’re not required to speak to anyone else. Don’t.
  • Write down what happened as soon as you can.
    As soon as you can, write down your complete recollection of the incidents occurring before, during, and after the accident. Describe everything you can remember, no matter how trivial: your physical feelings, weather, road conditions, traffic, behavior of other people… everything. Save a copy for your records. If your insurance claim goes to arbitration or trial, read this statement whenever you’re asked, “What happened?”
  • Get checked over completely.
    You may not need to go to the ER, but you should get checked out ASAP to document your condition. Be sure to mention every single pain, bruise, and feeling and verify that the doctor has written this down in your exam record. (ER docs don’t always make a note of conditions such as deep bruises if there’s no apparent trauma, but that doesn’t mean that these conditions aren’t real.) If you’re seeing a chiropractor or osteopath, get a full range-of-motion exam done within a couple of days, too.
  • Start a day log.
    The pain you may be in immediately after an accident is as nothing compared to the pain you’re going to be in two days later. To accurately document a claim for pain, suffering, and lost productivity, you need to keep a careful record of how you feel each and every day and what effect it’s having on you. Include any changes in your senses (particularly vision and smell), appetite, sex drive, memory, sleep patterns and dreams, or your ability to focus and work. You may make several entries a day for the first few weeks. Also be sure to record your emotions: depression, anger, and confusion are typical even several months later.
  • Don’t trust the other person’s insurance company.
    Regardless of whether you’re at fault or the victim, count on the other insurance company to circle their wagons. Give them the minimum necessary information; don’t admit or sign anything.
  • Don’t completely trust your insurance company, either.
    Your agent may be a great guy, but your insurance company is not likely to be on your side for a claim for productivity loss or pain and suffering (there are wonderful exceptions to this). While you should work with your insurance company, be aware that your and their interests may diverge, particularly if they’re going to be called on to use your underinsured motorist coverage. Remember that the first layer of insurance adjusters is often there to wear you down. If you are getting a lot of resistance, be sure to ask the question “Do you have the power to say ‘yes’ to what I’m asking you?” If the answer is “no” (usually), shift the focus of your argument to “Well, I’m wasting my time dealing with you. Who has the power to say ‘yes’?” You’ll at least be talking to the right person.
  • Consider hiring a lawyer, but don’t get one “just because.”
    Whenever you can settle something amicably without a lawyer, the world is a better place. But if the insurance companies are being difficult, you will need to get a good lawyer and have them go to bat for you. It’s always prudent to talk to a lawyer early on to find out the possible advantages of having representation, but remember that not all accident cases should be litigated. (And if you do get a lawyer, follow their advice.)
  • Don’t settle your claim too early.
    You’ve probably heard this before, but it’s true. Many deep tissue traumas don’t manifest until 6-12 months after the accident. If you settle too early and then have the onset of significant accident-related pain a few months later, you have little recourse for obtaining additional coverage.
  • Be reasonable.
    Nobody ever gets everything they deserve or want in the way of a settlement. Even with a good lawyer and a large insurance policy, you’ll only get a percentage of what you can claim for damages. Be prepared to compromise. If the insurance company makes you a settlement offer, discuss it with your lawyer and then sleep on it. If you can live with the offer and your lawyer recommends it, consider accepting it. Once the case is settled, you can move on with your life, which is the most important thing of all.

How to be immortal

A prefatory comment here: This is a speech I gave to a group of writers and technical communicators in the Society for Technical Communication. While some of the examples in this speech are pitched to writing, it doesn’t really matter. You can be immortal anywhere. And while I don’t normally worry too much about saying this, I want to make it darned clear that this piece is copyright 2000 by me, John Hedtke. I’m proud of this one and I don’t want it passing into the public domain. So there.


I’m going to tell you how to be immortal.

There are several ways.

The first is to live forever. (So far, so good for the lot of us, eh?) The next, which is pretty similar, is to avoid dying. (I think we’re all aces on that one, too.) Inasmuch as both of these methods take time — forever is going to take a while, after all — I have a method that may be a little faster. It’ll still take a while, but when you’re immortal, you can afford to take the long view.

(By the way, one of the nice things about immortality is that the opportunity to be immortal is open to everyone. Everyone can be immortal if they want to. This is not a zero-sum game. Everyone can win.)

I’d like to add that, as I present my method to you, there will be several references to concepts developed in Roman times. This proves two things: one, the Romans had a great deal of the way life works figured out several thousand years ago, and two, the time I spent in college wasn’t for nothing… it cost thousands of dollars.

The basis for the third method of being immortal is doing your part of the Great Work. If you haven’t heard that term before, the Great Work is a mystic thing—you’re never absolutely sure that this is The Thing you should be doing, but it’ll usually fall into the categories of “I think so” and “It’ll do until something better comes along.” The difference between our jobs and the Great Work is the difference between vocation and avocation: what we do to keep the cats in canned cat food and what we do to make the world a better place.

There’s more to it than this as well: If each person makes their contribution to the Great Work, it brings us to the Roman concept of communitas, the health and well-being of the community. Communitas is not a zero-sum game, either; the greater the communitas, the better the members of the community will be. In fact, communitas is the antithesis of a zero-sum game: if one person wins, then everyone wins! Not only does the Great Work make everyone’s life that much better, but it’s something outside yourself, a vital element of immortality.

My contribution to the Great Work seems to be helping people get jobs. (As a way to participate in the Great Work, it’s not bad; I encourage you to give it a try yourself.) Someone comes to you in need, sometimes rather desperate need, and they need to find a job. The people who most frequently ask me about finding jobs are new folks. We’ve all heard (and all asked at some point in our careers, so we should remember what this feels like) “How do I get started?” and “Where can I get experience?” We’ve got some stock answers for this: training, certificate programs, and so on, but we’re not usually very good about this: we, after all, are looking for folks with 2+ years experience, some Word and/or FrameMaker experience, a technical background, but surely someone down the road might be able to, uh….? The people who have that 2+ years of experience don’t usually need our help a tenth as much as the new kids. The new kids are the ones who need us the most.

I’ve always felt that helping someone get a job was the best thing you could do for them. Lots of things go into this: coaching them on interview skills, helping them structure their resumes to sell themselves more effectively, getting them up to speed on a new software package that’s The Hot Thing, providing internship opportunities, even teaching them basic “Dress-for-Success” skills. You can also give them the hand up that they need by putting them in contact with the person who needs someone with precisely their skill set. They take your advice, they get the job they’re after, and voila! They’re no longer in need. They feel good and so do you. All of this takes a lot of time and energy, but that’s okay; this is my personal contribution to the Great Work and I like doing it.

Keep in mind that nobody ever got where they were in life without someone, somewhere giving ‘em a break they didn’t rightly deserve. We need to ask ourselves “How do we pass on what we know and what we believe and what we think should be done?” We’re award-winning writers and editors and artists; now that we’re so cool, we need to pass it on and complete the cycle.

There are a lot of different ways to extend your energy in the STC to help people get a leg up, including:

  • Being the local job coordinator
  • Volunteering to be hospitality officer or a hospitality deputy
  • Hosting a picnic for the new people in your chapter at your house
  • Posting job information to the chapter job line and the newsletter
  • Sponsoring an internship at your company
  • Teaching a mini-seminar on a special skill
  • Teaching people to write good resumes
  • Helping someone assemble a portfolio
  • Hiring someone for a very small contract assignment for which their experience is a large part of the pay

What you do doesn’t have to be done in the STC; it can be in almost any venue. (I know, that’s nigh unto blasphemy with this group, but it’s true.) Go talk to a class of wannabe writers — I’ve talked to English and writing classes in high schools about the joys and wonders of being a freelancer and a non-fiction author. Even Creative Writing classes will be interested. You can be the treasured memory of some high school student’s junior year. Volunteer to be a job contact for your college through their alumni office: Lots of people who are in college are interested in asking questions of people who are working in a field that they’re interested in.

Helping people get jobs has an immediate payoff: both of you get a good feeling right away. Suppose you’ve been doing this for a while and helping people get started, move up, and move on to new jobs and experiences. Three, four, five years later, you’ll be looking for a job yourself. And the people that you’ve helped find a job are out in the community working, possibly not at the same job, but they’re launched on their own careers and moving ahead. The people you helped in the past can tell you about jobs that they now have to offer or positions they’ve heard about from peers. And if nothing else, they can provide references about what you’ve done for them and others in the past. You get to network a lot and meet a lot of great people. That’ll feel good, too.

When you’re immortal, it brings a lot of other things into perspective and we’re able to identify what’s important and what isn’t. Our jobs aren’t the important stuff. Here’s a case in point: At one point some years ago, I’d added 5 books to my bibliography in about 15 months and I was talking to my agent about the difficulties I was having juggling my rather pressing book schedule and the need to spend time in my relationship. My agent clarified things for me by saying “You know, when they’re lowering you into the ground, nobody’s going to be saying ‘Wow, that Hedtke! He got all his chapters in by May 31!'” The stuff we pump out during the day is what we do and how we pay the bills, but it’s not the really important stuff.

As a matter of fact, the things we do in our jobs tend to be of extremely limited value. We’re in a profession that makes what we do transient and even ephemeral. The things we write and draw usually have a lifespan of maybe a year or two; sometimes even less—a mere moment to someone who’s immortal. For example, when I was starting out in this business many years ago, I did documentation for tax preparation software. I knew that my writing was of finite value: after tax day on the 15th of April (an annual tax day being another Roman concept, by the way, for those of you taking notes), none of it would be of interest to any but a handful of late filers. (I see a few of you here tonight.) The value in this regard of the things we do in this regard is building a corpus of work and experience, but the value of individual old pieces is pretty small. At this point, I’ve got nearly 8 million words published, in the form of 26 books and close to 200 magazine articles and heaven alone knows how many manuals and online help systems since 1984, and, like the chambered nautilus, all but the most recent simply serve to show how much I’ve grown.

What is important is what we do when we’re immortal. We have an idea that the future is something we can see, sort of. If we just squinch our eyes up enough and peer into the sunset, we’ll be able to see what’s going to be happening. The Romans, you see, believed that the future creeps up on you from behind. No matter how much you looked over your shoulder, you could never see it. Anything you see in front of you is just going to be a pale shimmery reflection of what’s coming at you, sorta like trying to navigate when you’re driving at high speed by watching road haze on a hot day. And that’s why we’re so frequently surprised by the future: we can’t see it. So it’s a good idea to start working on being immortal now because no matter how much you may want to, you cannot start being immortal if you’re dead.

20, 30, 40 years from now, I hope that you all will have careers full of satisfactions, awards, and recognition. This will be wonderful, but your true measure of fame, your success in life, your immortality, is measured in how much you have helped other people and are kept alive for it in their memories and hearts.

And that brings me at last to the real secret of becoming immortal: decades from now, you’re going to be remembered by dozens, hundreds, possibly even thousands of people who you’ve been able to help get a new job, break into a new career, or publish their first book, and thereby start the cycle all over again. They’ll remember you fondly for the help you provided without strings, the energy you added to their lives, and the opportunities you gave them. You made a difference.

That’s immortality.

And it doesn’t get any better than that.


The 6 stages of UI design review

From Bonni Graham:

The 6 stages of UI design review (with apologies to Elizabeth Kubler-Ross)

  1. Fake cheer (“Welcome, everyone!”)
  2. Denial (“I can’t hear your stupid changes. La la la la la.”)
  3. Anger (“What I did is better!”)
  4. Justification (“This is why it’s better. Love me!”)
  5. Grudging acceptance (“OK, maybe it’s not better and your idea’s not totally stupid”)
  6. Adoption (“I love this idea!”)

Or maybe this is just me….


Final thoughts on submitting a book proposal

You can occasionally get a contract by coming up with a killer idea, phoning a publisher, pitching the idea over the phone, and hitting the jackpot… but you’ll stand a much better chance of getting the contract you want with the right publisher by making a planned presentation.

Most publishers let you submit via email or their website, but it may happen that you occasionally submit a proposal via snail mail. This is most likely to happen if you’re including samples of one kind or another that need to be printed. If so, don’t make the publisher return copies of anything to you! Publishers are up to their collective eyebrows in submitted material of various kinds (this bunch of stuff is known affectionately in the industry as “the slushpile”) and they don’t need the hassle of returning anything. Assume that anything you send to them won’t be returned; marking printed copies in red ink on the front page with “May be discarded after review” makes their lives even easier.

Remember that you’re selling your idea and your abilities as an author to the publisher, so it’s important for your proposal to shine. Publishers respond best to an idea if they can see that you’re excited about it, there’s a marketing niche, and that you know what to do to bring the book to fruition. If you think of your complete book proposal as a job interview by mail, you won’t be far wrong. Make sure the proposal is dressed well and looks good when it first meets the publisher.


Documentation plans–Part 2

There are six basic sections of a typical documentation plan:

  • overview
  • marketing
  • production information
  • staffing requirements
  • schedule
  • outline

Note: You can use the same general structure for documentation plans for contract writing assignments, manuals, or online help. The information you include varies depending on the type of writing project, but the overall format is the same.

The overview section states the scope and purpose of the project, defines the audience, gives the relationship to any other projects, and identifies the responsibilities of you and the publisher. It also identifies the general details for the handoff of the finished product (how many copies and in what general form). What you put in the overview is not a binding legal description unless the information is included by reference in the actual publisher’s contract (some publishers may want to do this), but it spells out a lot of details that might otherwise get lost or misinterpreted.

The marketing section identifies ways in which the book can be marketed. (Most publishers don’t expect authors to lift a finger to help them market, so showing that you’re able and willing to supply marketing opportunities may impress them.) Be sure that you can also point to the competition in the field—no publisher wants to walk into a heavily populated field without warning—and how and why this book will beat all of them. Also mention if there are opportunities for co-marketing or bundling with the product. Dan Gookin’s classic book DOS for Dummies was already a bestseller even before Microsoft bundled it with their MS-DOS 6.2 release; in its day, there were millions of copies in print. Riding on a product’s coattails will help you, and can frequently help the product, too. Don’t be afraid to aim high with your marketing ideas.

The production information section discusses what the finished product will look like, and how you intend to get there. What style will be used for the book? What format and page size? Art requirements? Some of this is dictated by the publisher, but you should be able to estimate the number of pages and the type and approximate quantity of illustrations your book will have. You’ll probably also have an idea of what the book should look like overall, so mention this in the proposal.

The staffing section discusses who will be doing the reviews and which kind. It also identifies the technical editor (usually a reviewer with background in the field you’re writing about), illustrator, proofreader, indexer, and other related personnel. At the beginning of a project, most of these are likely to be unknown.

The schedule section lists the proposed schedule along with any assumptions about the schedule. Be as specific as possible. Budget for vacations, holidays, and life requirements (such as doing taxes, birthdays, and so on). Leave yourself as much room as you can near the end of the book to make up time—there’s never enough.

Finally, the outline section presents an in-depth outline of the book. A detailed outline is a requirement for a good book proposal! The editor can clearly identify the focus of your book and offer specific suggestions before you begin writing on how to change or improve the book to better fit the publisher’s marketing plans.

By the way, a documentation plan is best when it’s a living document. As a project progresses, you should make changes to the plan to reflect changes in staffing, schedule, or (most importantly) the outline. Whenever you make a material change, you should also send a copy of the revised documentation plan to your editor so they’re up to date as well.

BTW, don’t worry if this seems a little unclear to you. This is a brief discussion of the general information you need in a documentation plan. If you have a format you like that covers this, then you can use it. If you don’t or you’d like to try something else, I’m going to be posting a detailed series on how to create a documentation plan, including information on how to use it and a downloadable template, as soon as I wrap up this set of blog posts.


Documentation plans–Part 1

The documentation plan is a useful and necessary project management tool before, during, and after a project. It presents information about the book’s scope, purpose, target audience, and goals, the book’s market niche, the standards and styles the book should adhere to, staffing requirements, the delivery schedule, and a detailed outline.

At the beginning, the documentation plan gives detailed information about the project to the publisher so they can make an informed choice about whether or not they want to publish the book. Once your idea has been approved, the plan serves to further clarify your and the publisher’s concept of the project. By writing down and agreeing to the scope and purpose, the goals for the book, and the schedule, you eliminate most of the causes of friction between you and the project editor.

During a project, a documentation plan is an effective scheduling and tracking tool. With each of the sections identified, you can gauge your progress compared to your original estimates. This information is helpful for avoiding writing crunches near the end of a project. With the schedule and outline information, you can also use the documentation plan as a tool for delegating sections of a project to subcontractors or other authors on the book.

Finally, the plan serves as a reminder of the scope, purpose, and goals of a book, a standard against which you can check your work. A documentation plan is essential for a post mortem analysis of the project. You can check your original assumptions and statements of the project against the finished product. By comparing your actual schedule against your estimates, you can pinpoint problems to avoid or plan for in the next project. This information is extremely valuable, as over the course of several books, you’ll learn how to estimate your time in each phase of a project very accurately. This can result in tighter schedules, which in turn can help you plan for more book contracts.


Adding your resume to a book proposal

If you’ve never pitched the publisher before and this is your first book, include a copy of your resume. Like any other job, you need to tailor the resume to underscore skills and accomplishments relating to the book and your skill set. For example, if you are pitching a book on using a particular graphics package and have a background or education in design, make sure that this is featured prominently in your resume.

Unlike a typical resume, though, you’re may have to include information that you wouldn’t typically include on a resume. For example, if you’re pitching a book on cooking safe and tasty desserts for diabetics, you’ll want to demonstrate that you have experience in cooking (and probably baking) and in writing. If your resume doesn’t show those skills, you need to include volunteer work or outside activities that demonstrate your skills. As an example, I have a friend who has a brilliant, readable, and fascinating manuscript that is a cookbook/history of cooking going from Roman times up to the early 20th C. It has over 800 recipes, 100% of which have been tested, with comments about the history and context. She hasn’t been able to get a publisher interested because she’s not a TV chef and has no visible standing in the field. There are ways around this, but it’s an obstacle.

Even if you look very hard, it’s possible that you don’t have a lot of resume credits to point to. You may be a dental technician during the day, but you have mad baking skills and you really can write very well. You may be a great dental technician, but you still need to make the case to the publisher that you, yes, you, are the one to manifest this amazing idea. Your writing samples are a great way to back your claim up, so if you don’t have a lot of experience that’s on-target, provide writing samples that make the case for you. (This is all much like garnering the experience for your first job, or your first job in a new field. Tailor your resume, cover letter, and writing samples to demonstrate your skills in writing the book.)