As technical writers, we’re often subjected to reviews by peers and editors. Although many people tend to lump these together, the two concepts are quite different.
A true peer review exposes your work to the scrutiny of others who are experts in the field documented by your work. It’s not editing. Editing is done for clarity and to make sure the author stays within the scope of work.
A peer reviewer assesses content for its technical accuracy. An editor reviews a document for its adherence to a specification.
Editors may review a document to determine if it communicates its purpose effectively. They also determine if the document conforms to style guidelines, not only ensuring good grammar, punctuation and style, but also validating organization and conformance to internal policies.
Technical writers normally don’t develop content to promote their own point of view. They express information in terms of their sponsor’s point of view, and it should be edited with this in mind. It’s almost like ghost writing.
A peer review process is applied to an original work subject to interpretation. Showing such work to others who possess a similar scientific or technical background increases the probability that errors in the research, the assumption, or the data will be identified and addressed.
===== Marc DiGiuseppe, Senior Consultant, Documentation Strategies
Tuesday, July 29, 2008
Friday, July 25, 2008
The Fine Line of Process Documentation
It’s likely that someday someone else will be doing the job you currently do today. They will thank you if you leave them a legacy of good process documentation. The person who will fill your void must learn how to do your job. That’s a tough process in itself because training people is often easier said than done.
The human mind tends to group tasks together once they are mastered. This can be a problem for someone learning the process for the first time. They must see each step individually, without your shortcuts, to fully understand what they need to do.
When you first start the documentation process you will be amazed at how many steps are in a simple daily procedure. Use something like filling in your time sheet as an example. You would think, “How would I explain filling in my time sheet?” Most likely your first answer would be a generic statement: I go to my computer, open up the file and fill it in. Though this statement is true, it is not the slightest bit helpful to someone who doesn’t already know where the file is located or how to fill out the form.
More information is needed. I sit down in my chair, breathe once, blink twice and use my right index finger to double click the right mouse button. More informative? Yes. Helpful? Not so much. When documenting a process one must find the “happy medium” between these two examples. You need to write something informative enough to help but not so detailed that it causes confusion.
When you are finished documenting the steps of the process you must then test them to make sure that what you have created is useful. To do this you need to find someone who doesn’t know anything about the process. Have them sit down with your document and see if they can complete the process. If they can complete it correctly and with minimal coaching, you have done a good job. If they cannot, not so good. All is not lost, however. Go back and revise the steps that caused the confusion. Try the test again, and if necessary repeat these steps until your test co-worker can complete the process with ease.
The main issue with process documentation is making it informative but concise. Write it so any average Joe can do your job. This is very important because the person who takes over your job will never be as smart as you, right?
===== Andrew Everett, Intern, Documentation Strategies
The human mind tends to group tasks together once they are mastered. This can be a problem for someone learning the process for the first time. They must see each step individually, without your shortcuts, to fully understand what they need to do.
When you first start the documentation process you will be amazed at how many steps are in a simple daily procedure. Use something like filling in your time sheet as an example. You would think, “How would I explain filling in my time sheet?” Most likely your first answer would be a generic statement: I go to my computer, open up the file and fill it in. Though this statement is true, it is not the slightest bit helpful to someone who doesn’t already know where the file is located or how to fill out the form.
More information is needed. I sit down in my chair, breathe once, blink twice and use my right index finger to double click the right mouse button. More informative? Yes. Helpful? Not so much. When documenting a process one must find the “happy medium” between these two examples. You need to write something informative enough to help but not so detailed that it causes confusion.
When you are finished documenting the steps of the process you must then test them to make sure that what you have created is useful. To do this you need to find someone who doesn’t know anything about the process. Have them sit down with your document and see if they can complete the process. If they can complete it correctly and with minimal coaching, you have done a good job. If they cannot, not so good. All is not lost, however. Go back and revise the steps that caused the confusion. Try the test again, and if necessary repeat these steps until your test co-worker can complete the process with ease.
The main issue with process documentation is making it informative but concise. Write it so any average Joe can do your job. This is very important because the person who takes over your job will never be as smart as you, right?
===== Andrew Everett, Intern, Documentation Strategies
Thursday, July 24, 2008
Authoring State vs. Federal RFPs: Different Strokes for Different Folks
At Documentation Strategies, we’re often asked to write a “Request for Proposal” (or RFP as it is commonly called) for a State Agency intent on purchasing a particular service or technology. Recently, we’ve started getting into RFPs for agencies of the Federal Government. We’ve noticed that there are differences in the manner in which RFPs are developed and written on the State and Federal level.
The State is usually focused on acquiring requirements specific to the issuing agency prior to defining the RFP. In other words, they’re usually focused on their existing business process and the procurement effort is driven by its requirements. The State agencies like to manage the design-build strategy for any particular procurement identifying the unique characteristics of their business process and how they believe the prospective contractor should address their expectations. State agencies aren’t too concerned with the size of the competing vendor as much as they are interested in that vendor’s depth of experience specific to their unique business requirements.
The Federal Government operates on a much different scope and scale. Federal Government RFP format and composition is mandated by the Federal Acquisition Regulation (FAR). They are typically broken down into sections that are identified by letter. There are 13 categories listed “A” through “M” covering topics from the scope of work to the applicable evaluation process. Federal Agencies are gradually being reorganized under performance-management-driven governance policies and are more focused on finding standard industry-accepted solutions to their business process management problems. Very often RFPs will ask the vendor to suggest a better approach to doing business that conforms to “best practices.” Federal agencies are interested in the capacity and capability of the competing vendor to deliver solutions that are compliant with these best practices and industry standards. On large-scale projects they sometimes conduct a “phase 1 down-select” to determine who will be permitted to compete on the “phase 2 RFP.”
State agencies sometimes issue RFIs (Requests for Information) to help them determine who is really capable of addressing the specific requirements of the RFP under consideration. This approach is somewhat similar to the Federal Government’s “down-select” process. However, RFIs usually are solicited to help the agency subject matter experts bone up on what they can expect from the private sector in the way of solutions. Rarely are vendors excluded because of an RFI.
Another feature we’ve noticed in Federal RFP strategy is an emphasis on oral presentation. The Federal evaluators expect the prospective vendor to have a pronounced and apparent command of the subject matter and applicable expertise. This lets them know how much of a risk the vendor might be in getting the job done should they be selected. Though there is a great deal of emphasis on sharing the pie with small business, it is the large established vendors that normally enjoy success as the winner or “The Prime.” But the Federal Government has a creative and equitable solution to address capacity expectations. On very large RFPs, the Federal Government allows competing vendors and approved small businesses to “partner” with the Prime as a subcontractor. In this fashion, the agency can draw in the best from each vendor and enjoy advantages unique to small business.
======= Marc DiGiuseppe, Senior Consultant, Documentation Strategies
The State is usually focused on acquiring requirements specific to the issuing agency prior to defining the RFP. In other words, they’re usually focused on their existing business process and the procurement effort is driven by its requirements. The State agencies like to manage the design-build strategy for any particular procurement identifying the unique characteristics of their business process and how they believe the prospective contractor should address their expectations. State agencies aren’t too concerned with the size of the competing vendor as much as they are interested in that vendor’s depth of experience specific to their unique business requirements.
The Federal Government operates on a much different scope and scale. Federal Government RFP format and composition is mandated by the Federal Acquisition Regulation (FAR). They are typically broken down into sections that are identified by letter. There are 13 categories listed “A” through “M” covering topics from the scope of work to the applicable evaluation process. Federal Agencies are gradually being reorganized under performance-management-driven governance policies and are more focused on finding standard industry-accepted solutions to their business process management problems. Very often RFPs will ask the vendor to suggest a better approach to doing business that conforms to “best practices.” Federal agencies are interested in the capacity and capability of the competing vendor to deliver solutions that are compliant with these best practices and industry standards. On large-scale projects they sometimes conduct a “phase 1 down-select” to determine who will be permitted to compete on the “phase 2 RFP.”
State agencies sometimes issue RFIs (Requests for Information) to help them determine who is really capable of addressing the specific requirements of the RFP under consideration. This approach is somewhat similar to the Federal Government’s “down-select” process. However, RFIs usually are solicited to help the agency subject matter experts bone up on what they can expect from the private sector in the way of solutions. Rarely are vendors excluded because of an RFI.
Another feature we’ve noticed in Federal RFP strategy is an emphasis on oral presentation. The Federal evaluators expect the prospective vendor to have a pronounced and apparent command of the subject matter and applicable expertise. This lets them know how much of a risk the vendor might be in getting the job done should they be selected. Though there is a great deal of emphasis on sharing the pie with small business, it is the large established vendors that normally enjoy success as the winner or “The Prime.” But the Federal Government has a creative and equitable solution to address capacity expectations. On very large RFPs, the Federal Government allows competing vendors and approved small businesses to “partner” with the Prime as a subcontractor. In this fashion, the agency can draw in the best from each vendor and enjoy advantages unique to small business.
======= Marc DiGiuseppe, Senior Consultant, Documentation Strategies
Wednesday, July 2, 2008
Everyone Needs an Editor
"The chassis should move in and out smoothly. If it does not pull the unit out, depress the clip releases on each side and carefully remove the appliance from the rack."
"Once the appliance moves smoothly along the rails tighten all accessible screws"
These are recent tidbits from my file of ambiguous technical writing. Ponder this:
- Is the chassis designed to pull the unit out?
- Is it OK to leave unaccessible screws loose?
Hint: After you write it get someone to read it. Their interpretation may differ.
=== Jeff Klein, COO, Documentation Strategies
Tuesday, July 1, 2008
Droll Tech Writers Go High-Class
Here's some of the DocStrats team who were in the office on Friday, June 27th for our Ugly Shirt Contest. From left to right, they are Jeff, Mary Leu, Adam, Ann, Slade, Marc, Andrew and Preetham. Luckily the camera lens did not break...
Wednesday, June 25, 2008
How Not to Get Hired at DocStrats
We get several resumes each week from people wanting to become technical writers. A distressingly large percentage of these resumes hit the trash within five minutes of arrival. Why? Read on for some tips on how not to get hired at DocStrats:
1) Address your cover letter to “Whom It May Concern”. It’s much too difficult to check our website and give us a call to get the right person’s name.
2) Indicate that your most recent job ended in 2004 and don’t tell us why. After all, it’s up to us to determine if you’ve been sailing around the world, in prison, or just forgot where you work.
3) Stress lots of inappropriate experience. You’re the finest mattress salesperson in the world? Best of luck with your career.
4) Don’t proofread your resume. Don’t fix the typos or the poor grammar, and by all means continue confusing it’s with its and there with their. Catching these mistakes is up to Microsoft Word, not the author.
5) Embellish your credentials. How could we not hire a PhD and Attorney with sixty years’ experience designing nuclear missile systems while working at the State Department?
Got it?
====== Jeff Klein, COO, Documentation Strategies
1) Address your cover letter to “Whom It May Concern”. It’s much too difficult to check our website and give us a call to get the right person’s name.
2) Indicate that your most recent job ended in 2004 and don’t tell us why. After all, it’s up to us to determine if you’ve been sailing around the world, in prison, or just forgot where you work.
3) Stress lots of inappropriate experience. You’re the finest mattress salesperson in the world? Best of luck with your career.
4) Don’t proofread your resume. Don’t fix the typos or the poor grammar, and by all means continue confusing it’s with its and there with their. Catching these mistakes is up to Microsoft Word, not the author.
5) Embellish your credentials. How could we not hire a PhD and Attorney with sixty years’ experience designing nuclear missile systems while working at the State Department?
Got it?
====== Jeff Klein, COO, Documentation Strategies
Subscribe to:
Posts (Atom)