- You have to love writing.
- You have to love reading.
- You have to love words.
- You have to love the linguistic and grammatical things that come with writing.
- You have to understand the nuances and multiple meanings and the synonyms and homonyms and antonyms (and definitely know what they are).
- You have to know and love the differences between a simile and a metaphor.
- And most of all, you MUST WRITE.
EditorDave at the Keyboard: Thoughts about writing--technical, scientific, and that for general audiences--based on 30+ years of experience.
Friday, March 16, 2012
Technical WRITING is first, and foremost, WRITING!
The key word in the title "Technical Writer" is the word "Writer."
Wednesday, March 7, 2012
Documentation Project -- Getting Started
If you don't know where you are going -- your destination -- then it probably doesn't matter how, when, and where you get to one.
The same goes for a documentation project. You must have a goal. A final expectation. A destination. In the documentation world, this is usually called a "deadline".
And, of course, you will have milestones along the way that will let you know where you are and what you must do next to move along to the next milestone.
What's a "documentation project"?
For instance, in your writing class, when your instructor gives you a writing assignment, you are told a topic you must write about and the deadline for submitting the document. These may be the basic requirements for the document. The instructor may leave you with only those requirements and expect you to figure out the rest, or the instructor may be more specific by asking for a page count, page size, page margins, illustrations, line spacing, font size, and so on. They might even specify the number of references to cite and other requirements.
This example is not much different from what you'll find when you get out of school and into the world of work.
In journalism, such as writing for magazines and newspapers, the critical piece of the puzzle is the deadline. If you miss the deadline, you've missed the boat and lost the trophy (and yes, I know I'm mixing metaphors. But you get the point). Deadlines are all-important in the magazine and newspaper business--there's a time when the presses must run and any additional input must be stopped so the compositors and layout folks can create the final galleys for making the plates for the presses.
This is changing a lot with new technologies. With digital content development, composition, design, layout, and even typesetting, a lot of the different hand-offs during document production is eliminated. But the deadlines remain.
Similarly, in the corporate and business world, the documents also tend to have deadlines. But unlike the deadlines in media (newspaper and magazine printing plant deadlines), the deadlines in the corporate world can move in either direction frequently throughout the project. Yup, the project team (usually a "product team", and documentation is only a small part of this project) can pull back a deadline by a few weeks or even a month to accommodate an early beta release of the product. Or, because they've had some problems in engineering, they'll slip the project deadline for a few weeks or a month or two to allow them to do some "bug scrubs" and "bug fixes".
So, you may wonder, "How in the world do you plan a documentation project with this kind of behavior exhibited by all the players?"
From the previous two posts, you might think that you know the "metrics" and "brainstorming" for a documentation project. But when presented with the vagaries of documentation as described in this post, you will again be at a loss.
Does it happen like this on construction projects? Where the participants all know the cubic yards of concrete required for the foundation (and also know the drying times for the specific kind of concrete), the linear feet of rebar reinforcements for that same concrete, the amount of lumber yardage, plumbing fixtures, and even down to amount of nails and fasteners?
There seems to be a difference.
Construction Projects
When notified that you'd be working on a construction project, if you were an experience construction professional, you'd scope out the area where the construction would take place or the building to which the remodeling would happen. You'd get your environmental impact assessment reports, your soil analyses, your county surveyor's records, and your zoning requirements all gotten together and assembled. Then, you'd walk the area and scope out the project--the general area and dimensions of the project, the elevation of the project, and a loose estimate of the materials, the number of workers, and the time needed to complete the project. According to one of my tech writing instructors, this would be called a "SWAG--Scientific Wild-Assed-Guess"--good for a "ball-park" estimate to start with putting form to the idea of the project.
Then you'd get down to the detailed nitty-gritty analysis of the project. You'd develop the various engineering drawing layers--for the grading and trenching of the lot area, for the reinforcing rebar and foundation, for the framing, for the electrical and plumbing, for the walls, for the roof, for the drop-ceiling, for the ventilation, for the doors/windows, and so on. Then, you'd calculate the number of cubic yards of concrete; the linear feet of rebar, lumber, electrical wiring, plumbing, and masonry; and for amount of fasteners, nails, paint, stucco, and finishing touches. These figures would then be added for the material costs. Then, you'd need to create timeline based on the size of your construction crew--the number of workers determines how fast you can grade the area, dig the trenches, lay the rebar, pour the concrete, put in the framing, add the roof, add the walls, add the doors and windows, and complete the finishing. Other factors determine the timing of your project that have nothing to do with the number of your workers--these would include the physics of drying concrete and drying paint.
From all these component calculations -- for the engineering drawings, for the estimates derived from those drawings on needed materials, for the industry-established timing metrics for the tasks involved with the project, and for the number of workers allotted for the project, you can come up with a project budget and timeline with milestones and the deadline. The deadline may be a little flexible with certain jobs that could be worked on simultaneously or by adding additional workers, but the project timeline would be a somewhat dependable indication of when the project would be completed. You could even add these figures to project calculation software, perhaps like Microsoft Project, to make nice charts in various forms such as Gantt Charts or PERT Charts that would show all the timelines heading for the various milestones and the ultimate deadline of completion. The dependencies would be shown and the chart would make it easy to see where compression of tasks could occur to make the project most efficient and where savings could be implemented.
Documentation Project
Yeah, they may know that they want a document (but sometimes even that isn't happening). And then they tell you when they want it -- their deadline. And they tell you a day before they need it. Well, maybe not that bad, but sometimes it seems they pull their deadline out of their hat (or from somewhere else). And they haven't taken account of the complexity of their subject matter, the availability of their subject matter experts or reference sources, the availability of illustrations or an illustrator, or the number of pages they need to create. But they have their deadline.
And they'll tell you. They want a 100-page document pushed out with a month-long deadline. Sure, they'll tell you what they want for a topic. They may provide you with some research materials and some subject matter experts to talk to. But you are going to need to ask them a lot of tough questions to clarify what they want and why they want it (sometimes they don't know why, but they feel they need it). Who is the intended audience? What is their reading level and need for the information? How many illustrations will you need? Is someone available to help with the illustrations, or do they expect you to do them? Is there a document template, or will you need to create one?
You can try to put this information into a Microsoft Project application file, but because the application depends on adding the metrics to come up with a deadline (as how it's designed to do... and it works quite well with construction projects) rather than stating a deadline and then just faking the timelines all based on the deadline, this only creates a pretty diagram that is essentially meaningless.
Sort of.
Most professional tech writers can, nevertheless work from that pretty schedule and produce a document within the required deadline. But in most cases this isn't cheap--particularly if they are concerned about quality.
Eventually those who want to have a document produced will learn that they can have their documentation project with three major criteria:
cheap, quick, and quality.
The problem is... without good planning and scheduling, only two of those options are options. One of them will always have to go as an expense of the others.
The same goes for a documentation project. You must have a goal. A final expectation. A destination. In the documentation world, this is usually called a "deadline".
And, of course, you will have milestones along the way that will let you know where you are and what you must do next to move along to the next milestone.
What's a "documentation project"?
For instance, in your writing class, when your instructor gives you a writing assignment, you are told a topic you must write about and the deadline for submitting the document. These may be the basic requirements for the document. The instructor may leave you with only those requirements and expect you to figure out the rest, or the instructor may be more specific by asking for a page count, page size, page margins, illustrations, line spacing, font size, and so on. They might even specify the number of references to cite and other requirements.
This example is not much different from what you'll find when you get out of school and into the world of work.
In journalism, such as writing for magazines and newspapers, the critical piece of the puzzle is the deadline. If you miss the deadline, you've missed the boat and lost the trophy (and yes, I know I'm mixing metaphors. But you get the point). Deadlines are all-important in the magazine and newspaper business--there's a time when the presses must run and any additional input must be stopped so the compositors and layout folks can create the final galleys for making the plates for the presses.
This is changing a lot with new technologies. With digital content development, composition, design, layout, and even typesetting, a lot of the different hand-offs during document production is eliminated. But the deadlines remain.
Similarly, in the corporate and business world, the documents also tend to have deadlines. But unlike the deadlines in media (newspaper and magazine printing plant deadlines), the deadlines in the corporate world can move in either direction frequently throughout the project. Yup, the project team (usually a "product team", and documentation is only a small part of this project) can pull back a deadline by a few weeks or even a month to accommodate an early beta release of the product. Or, because they've had some problems in engineering, they'll slip the project deadline for a few weeks or a month or two to allow them to do some "bug scrubs" and "bug fixes".
So, you may wonder, "How in the world do you plan a documentation project with this kind of behavior exhibited by all the players?"
From the previous two posts, you might think that you know the "metrics" and "brainstorming" for a documentation project. But when presented with the vagaries of documentation as described in this post, you will again be at a loss.
Does it happen like this on construction projects? Where the participants all know the cubic yards of concrete required for the foundation (and also know the drying times for the specific kind of concrete), the linear feet of rebar reinforcements for that same concrete, the amount of lumber yardage, plumbing fixtures, and even down to amount of nails and fasteners?
There seems to be a difference.
Construction Projects
When notified that you'd be working on a construction project, if you were an experience construction professional, you'd scope out the area where the construction would take place or the building to which the remodeling would happen. You'd get your environmental impact assessment reports, your soil analyses, your county surveyor's records, and your zoning requirements all gotten together and assembled. Then, you'd walk the area and scope out the project--the general area and dimensions of the project, the elevation of the project, and a loose estimate of the materials, the number of workers, and the time needed to complete the project. According to one of my tech writing instructors, this would be called a "SWAG--Scientific Wild-Assed-Guess"--good for a "ball-park" estimate to start with putting form to the idea of the project.
Then you'd get down to the detailed nitty-gritty analysis of the project. You'd develop the various engineering drawing layers--for the grading and trenching of the lot area, for the reinforcing rebar and foundation, for the framing, for the electrical and plumbing, for the walls, for the roof, for the drop-ceiling, for the ventilation, for the doors/windows, and so on. Then, you'd calculate the number of cubic yards of concrete; the linear feet of rebar, lumber, electrical wiring, plumbing, and masonry; and for amount of fasteners, nails, paint, stucco, and finishing touches. These figures would then be added for the material costs. Then, you'd need to create timeline based on the size of your construction crew--the number of workers determines how fast you can grade the area, dig the trenches, lay the rebar, pour the concrete, put in the framing, add the roof, add the walls, add the doors and windows, and complete the finishing. Other factors determine the timing of your project that have nothing to do with the number of your workers--these would include the physics of drying concrete and drying paint.
From all these component calculations -- for the engineering drawings, for the estimates derived from those drawings on needed materials, for the industry-established timing metrics for the tasks involved with the project, and for the number of workers allotted for the project, you can come up with a project budget and timeline with milestones and the deadline. The deadline may be a little flexible with certain jobs that could be worked on simultaneously or by adding additional workers, but the project timeline would be a somewhat dependable indication of when the project would be completed. You could even add these figures to project calculation software, perhaps like Microsoft Project, to make nice charts in various forms such as Gantt Charts or PERT Charts that would show all the timelines heading for the various milestones and the ultimate deadline of completion. The dependencies would be shown and the chart would make it easy to see where compression of tasks could occur to make the project most efficient and where savings could be implemented.
Documentation Project
Yeah, they may know that they want a document (but sometimes even that isn't happening). And then they tell you when they want it -- their deadline. And they tell you a day before they need it. Well, maybe not that bad, but sometimes it seems they pull their deadline out of their hat (or from somewhere else). And they haven't taken account of the complexity of their subject matter, the availability of their subject matter experts or reference sources, the availability of illustrations or an illustrator, or the number of pages they need to create. But they have their deadline.
And they'll tell you. They want a 100-page document pushed out with a month-long deadline. Sure, they'll tell you what they want for a topic. They may provide you with some research materials and some subject matter experts to talk to. But you are going to need to ask them a lot of tough questions to clarify what they want and why they want it (sometimes they don't know why, but they feel they need it). Who is the intended audience? What is their reading level and need for the information? How many illustrations will you need? Is someone available to help with the illustrations, or do they expect you to do them? Is there a document template, or will you need to create one?
You can try to put this information into a Microsoft Project application file, but because the application depends on adding the metrics to come up with a deadline (as how it's designed to do... and it works quite well with construction projects) rather than stating a deadline and then just faking the timelines all based on the deadline, this only creates a pretty diagram that is essentially meaningless.
Sort of.
Most professional tech writers can, nevertheless work from that pretty schedule and produce a document within the required deadline. But in most cases this isn't cheap--particularly if they are concerned about quality.
Eventually those who want to have a document produced will learn that they can have their documentation project with three major criteria:
cheap, quick, and quality.
The problem is... without good planning and scheduling, only two of those options are options. One of them will always have to go as an expense of the others.
Friday, March 2, 2012
Metrics -- The Measurements that are the Substance of Documentation
When it comes to documentation, where do the numbers come from?
It used to be relatively easy:
Typewriters had monotype fonts (such as what you see as the computer font called Courier), and manuscript standards required 1-inch margins and double-line-spacing between the lines of text on 8-1/2" X 11" pages of paper (in the U.S.A. -- in other countries, perhaps it was "A4" paper).
In any case, this would result in the average page containing about 250 words. So, four typewritten pages contain about 1000 words. (These are considered "manuscript" pages and NOT "finished" or "published" pages.) What is captured here is the CONTENT of the document.
Then, you have the times involved with creating a document. Again, there are many ways to come up with these figures.
A researcher in technical documentation stated in her seminars that a standard printed (finished) document project in Silicon Valley (or most likely anywhere else) would require 8 hours per page. Using this figure, one could calculate that a 100-page finished document would require 800 hours of work. If you consider that with 8 hours a day (a page a day), that would be 100 days, or 20 weeks, or 5 months of work. From start to finish.
Before you think this is excessive, consider this: Included in this figure are the times for scoping the project, planning the project, budgeting the project, researching the content source material, consulting with subject matter experts on the target content, writing the rough draft, creating the illustrations, reviewing the preliminary document draft, editing, preparation of the final document, and printing and/or coding for web viewing.
So, when you think you have an extremely slow writer who can do only one page per day, that's not the right way of looking at the picture. The first few weeks of a documentation project might not show ANY writing being done. This time would be spent with the scoping, planning, budgeting, and researching the content source material (if any). Pages of a document are not usually worked on during this time--but that does not mean that the time spent doing the mentioned work isn't critical for a successful project. This preliminary work is critical.
Once this preliminary work is completed, a good tech writer may be able to churn out 4 to 8 pages per day (because the previous work compiled enough notes from the source material to give substantial material for the base content). If a separate illustrator can be employed to help out, the artwork can be done simultaneously--thus compressing the time a bit for producing the document. If a separate editor and layout specialist can be employed, the document end time can also be further compressed. Unfortunately, many times the writer is responsible for everything--doing the research, doing the writing, doing the layout, doing the illustrations, conducting the reviews with the subject matter experts (SMEs), and sometimes even converting the document to final (without other-person editing and review). Sometimes the writer even has to contract and negotiate the printing production of a document.
So, if the documentation project is a one-person job, the longest time period may be a good estimate (100-page document = 800 hours). If the writer is an inexperienced writer, the job will take longer. If the writer is experienced not only with the tools of the trade, but also with the content material and the type of document, the time for completion can be compressed.
What's your writing time? Pull out a stopwatch or digital timer--then start keyboarding about something you are familiar with. Stop after perhaps 4 to 10 pages of 12-pt monospace font, double-line-spaced, 8-1/2" X 11" pages. (If you are using MS-Word, you can select the Word Count/Statistics tool from your main toolbar to get the number of words you have produced and the amount of time you have taken to do so.) If you do this a few times for various topics, you can start to create a set of sessions from which you can calculate your average time per page. This is a good figure for starters.
What's your editing time? Again, pull out a stopwatch or digital timer--then start reading through some document manuscript pages (12-pt monospace font, double-line-spaced, 8-1/2" X 11" pages) that you perceive as not-too-easy and not-too-complicated. Try for about 5 to 10 pages. Then, once you've hit that number of pages, see how long it took you to go through those pages. Now, you have your average time per page. With MS-Word manuscript pages, you can easily do a word-count of those pages and come up with an average time for a certain number of words (for example, 1000 words), to provide the figure for wordcounts when the pages don't match the standards for the metrics (for example, when you get a document in 8pt, kerned font such as Times-Roman or Palatino, and on smaller or larger pages).
I'm keeping it simple here. Because many additional factors have an effect on documentation project times. Factors such as the complexity of the content, the target audience, the availability of your subject matter experts, the availability of your source/research materials, the number of staff assigned to produce the document, the type of document required, the number of illustrations required, and so on.
But this should at least give you an idea about the metrics involved with a documentation project. These metrics are critical for further planning and scheduling (and budgeting) in a documentation project.
Wednesday, February 29, 2012
What's the point with writing? How about preplanning?
Do you ever get started on your keyboard and you realize that you don't have much to say? Do you then sit there staring at the blank white page or screen for seemingly hours or do you just start keyboarding such that words start flowing onto the page?
That's the dilemma with any type of writing--where to start and what to start.
So, it would be wise to maybe kick around some ideas on a notepad or whiteboard, or hey, even a napkin, before even starting the writing project.
I'm not talking about wild posts on Facebook or Twitter or even emails to your group on Google or one of the other email providers. I'm talking about writing that you want to use to showcase your thoughts and even your personality.
After making much of my career with writing over the past 35 years, I'd like to share my thoughts with you.
Ever since I started writing -- maybe even when I was in junior high school -- when I get the glimmer of an idea for an article (for a newspaper or magazine) or other type of document, I jot notes on a small notepad or even in a three-ring binder to fill out the idea's form and give it more substance.
Although I still do that (I always have a few pens and some paper handy when I'm out and about), I've found that having a whiteboard handy in my office helps for fleshing out those ideas.
What is this? Brainstorming! And it's a form of Preplanning!
It's a technique that I learned when I started in college and worked part-time at a marine laboratory. The scientists had blackboards in their offices on which they'd scope out their research projects. Sure, scientific reports and journal articles have a set organization as dictated by their fields, but they still have to plan their research approach. And the researchers seemed to get a better handle on their upcoming work by getting some of the most pertinent points on their boards so they could start aiming their thoughts in those directions.
I've learned to do the same -- for my fun writing as well as for my work writing. I did this a little for this post as well--just some notes on a piece of paper for things I wanted to discuss here.
As a Squidoo fan, I love creating fun Squidoo lenses (what Squidoo calls the sites that folks make on their site) that showcase my writing and photography (and generate a little cash, too!). And for most of my Squidoo lenses, I get the idea while I'm out driving around or some other place where I can't just start getting it captured by keyboard. So I'll just jot a note on a piece of paper so I can get to it later. Then, I carry that paper around and add to it as I think of more angles or items I can add.
But a Squidoo lens, like this blog post, is not a formal document. So I don't feel a need to wait until it's perfect or darned close before I release it to the world. I try to get it as robust as possible, but I'd rather get something out than to let it sit for days, weeks, and months before it is published. Yes, I occasionally find typos or unclosed parentheses or broken links--the nice thing about this blogging platform and my Squidoo lenses is that I can always go back into the post and fix the problems. Sometimes you have to look at a post (or publication) with fresh eyes before you can see the issues that could use polishing.
Do you wonder what a Squidoo lens looks like? Here is one of my first ones: "If You Write--Get it Edited".
That's the dilemma with any type of writing--where to start and what to start.
So, it would be wise to maybe kick around some ideas on a notepad or whiteboard, or hey, even a napkin, before even starting the writing project.
I'm not talking about wild posts on Facebook or Twitter or even emails to your group on Google or one of the other email providers. I'm talking about writing that you want to use to showcase your thoughts and even your personality.
After making much of my career with writing over the past 35 years, I'd like to share my thoughts with you.
Ever since I started writing -- maybe even when I was in junior high school -- when I get the glimmer of an idea for an article (for a newspaper or magazine) or other type of document, I jot notes on a small notepad or even in a three-ring binder to fill out the idea's form and give it more substance.
Although I still do that (I always have a few pens and some paper handy when I'm out and about), I've found that having a whiteboard handy in my office helps for fleshing out those ideas.
What is this? Brainstorming! And it's a form of Preplanning!
It's a technique that I learned when I started in college and worked part-time at a marine laboratory. The scientists had blackboards in their offices on which they'd scope out their research projects. Sure, scientific reports and journal articles have a set organization as dictated by their fields, but they still have to plan their research approach. And the researchers seemed to get a better handle on their upcoming work by getting some of the most pertinent points on their boards so they could start aiming their thoughts in those directions.
I've learned to do the same -- for my fun writing as well as for my work writing. I did this a little for this post as well--just some notes on a piece of paper for things I wanted to discuss here.
As a Squidoo fan, I love creating fun Squidoo lenses (what Squidoo calls the sites that folks make on their site) that showcase my writing and photography (and generate a little cash, too!). And for most of my Squidoo lenses, I get the idea while I'm out driving around or some other place where I can't just start getting it captured by keyboard. So I'll just jot a note on a piece of paper so I can get to it later. Then, I carry that paper around and add to it as I think of more angles or items I can add.
But a Squidoo lens, like this blog post, is not a formal document. So I don't feel a need to wait until it's perfect or darned close before I release it to the world. I try to get it as robust as possible, but I'd rather get something out than to let it sit for days, weeks, and months before it is published. Yes, I occasionally find typos or unclosed parentheses or broken links--the nice thing about this blogging platform and my Squidoo lenses is that I can always go back into the post and fix the problems. Sometimes you have to look at a post (or publication) with fresh eyes before you can see the issues that could use polishing.
Do you wonder what a Squidoo lens looks like? Here is one of my first ones: "If You Write--Get it Edited".
Subscribe to:
Posts (Atom)