PwordJournal

The technical review can be a source of annoyance and contention, or it can hone your technical communications into precise targeted documents that help customers solve a problem, help  products pass quickly through a regulatory review, or help the sales force quickly understand the product. Here are some guidelines for a smooth technical review process.

Have a process and a schedule. Do you scramble to write documentation just before a product is ready to ship, or just before an important regulatory review? If so, you are asking for technical reviews at crunch time — exactly the time when subject matter experts (SMEs) are least able to provide thoughtful input. Design a process that allows writers to attend early meetings and write early drafts. Build in reasonable time for reviewers reasonable timeframes to review the documents. Give writers reasonable timeframes to revise the documents.

Get “Buy-in.” The main reason that subject matter experts do not want to participate in technical reviews is lack of time. If they don’t understand why they are asked to review a document, they will not want to use valuable time to do it. Announce the process, make sure that people are aware that they will be asked to review documents. Emphasize the reasons why you are asking for a review. For example, technical reviews are important because:

• The technical writer sees the product from the end user perspective. Reviewing the document may identify missing, incomplete, or ambiguous information. A technical review can help find problems before customers do!
• A good technical document will bring regulatory approval more quickly than products with missing or vague documentation.
• Good technical communications will help sales by making products easy to understand and use for the sales force, and for customers.
• A good technical document will reduce the time, effort and money your company spends troubleshooting or supporting your product.

Provide clear instructions for the review. Provide a detailed summary about what you expect from the review. For example, “Please review this document for accuracy — the document will undergo a complete copy edit prior to publication.” This way, you will get substantive comments, rather than quibbles about punctuation or layout. Clear instructions can point out problem areas so reviewers can focus on new, or complex material. I like to provide a checklist to help guide reviewers to the kind of review I need. This saves time for everyone.

Establish Accountability. Indicate when the review comments are due, and why. Also, it helps to be flexible where it is impossible to review the document within the requested timeframe. Depending on the situation, the writer and SME can agree on a new date. If an SME is not able to review the document within your timeframe, ask them to designate a reviewer who can review the content in the same capacity (e.g., Marketing, Regulatory, etc.). SMEs who don’t notify the writer or designate another reviewer should understand that their comments will not be incorporated.

A smooth technical review process is an essential part of the product life cycle. With an understanding of your engineering process and good planning, good reviews will become routine.

A recent post on a science writers’ list, asked for advice on becoming a technical writer. As a technical writer with an education in science journalism, this got me thinking about how these forms of communication are similar, and how they are different.

Technical writing and science writing have different goals.

Technical writing facilitates the user’s ability to complete a task or understand a concept. Every part of the process, from gathering information, to structuring and revising it should be done with these goals in mind.

Science writing, particularly science journalism, seeks to help its audience understand science by presenting the facts in an engaging and interesting narrative.

Technical writing and science writing have different structures

Good technical writing is a series of compact and concise procedures that allow the user to accomplish a task. Depending on the task, the procedure will require some context setting; a conceptual framework that helps the user accomplish the task, and a procedural component that provides the steps to accomplish the task. Finally, it is the responsibility of the technical writer to link these components in a way that facilitates understanding of the sum of the tasks. Three very specific types of information appear in all good technical writing: conceptual information, procedural information, and a series of coherent references to the first two elements.

Science writing has a narrative structure. Each concept is supported with facts or evidence that helps the reader build an understanding of the topic(s). The end result is an engaging story that brings new information or a new understanding. The structure moves from general to specific and back again to help provide context for the facts. The structure depends on the medium, but the key elements are: the facts, the story, and the audience.

Technical writing and science writing use some of the same skills for different goals

Good technical writing requires a feel for the audience, the ability to select information that meets the needs of that audience, and the ability to write precisely, concisely and accurately. It also requires the ability to “find out” the truth by interviewing, researching and analyzing. As a technical writer, you must often balance the conflicting agendas of marketing, engineering and user requirements to identify the best “truth” for the users. If you are considering a career as a technical writer, you will be a lot happier in your work if you have these skills.The more I think about it, the more I realize, that my journalistic skills have been a very large part of my technical writing success. In my experience, technical writing is 80% research, information gathering and analyzing, and 20% writing.

To accomplish its goals, science writing, particularly science journalism — tells a story. In science writing, and indeed in life, “Everything is a story.” It is the narrative structure, I think, that makes science writing different from technical writing. Good science writing asks a question and reveals the possible answers in ways that let the reader experience a sense of discovery — a sense of how the scientific process “feels.” You need not be a scientist to do this, but you must have good research skills, an analytical mind, and understanding of how science works, and a healthy sense of skepticism about the “truths” that you uncover.

In 1981, when I entered the Boston University program in Science Communication (now called the Graduate Program in Science Journalism), I became fascinated with how computers make words and pictures. I started my technical writing career by documenting the first word processors at Wang Laboratories. I followed my curiosity to learn about how these things worked, wrote about it for users, and became a technical writer (there were very few formal technical writing programs then)! Now, many years later, as I return to science writing, I realize that I’ve been using those science writing skills all along. —Science writers who want to be technical writers (or vice versa) can use the ability to understand audiences, good research and analytical skills, and the ability to write clearly, concisely and accurately for both endeavors.

Recent studies of the horse’s biological clock — the mechanisms that maintain the horse’s biological rhythms – provide new insights into optimum ways of feeding, housing, medicating, and perhaps even training and exercising horses. Like other mammals, horses have a “master pacemaker” that controls body rhythms and orchestrates cell-based “peripheral clocks” that regulate aspects of the horse’s physiology, such as activity cycles, metabolism and immunity.

Barbara Murphy PhD, and Lecturer in Equine Science at the School of Agriculture, Food Science and Veterinary Medicine at University College Dublin is interested in how these clocks work in the horse. Using the recently mapped equine genome to pinpoint the genes that control the clock mechanisms, Murphy was able to characterize the intricate feedback system that synchronizes the horse’s body to its environment, and allows it to adapt to its surroundings.

Unlike other mammals, the horse seems capable of more rapid adjustments to the environment. This allows them to adjust to the 24-hour diurnal patterns humans impose. By monitoring activity patterns Murphy observed how the horse’s biological clock works without the diurnal cycles imposed by humans.

Under conditions more like their natural environment, the horse shows ultradian rhythms – short bursts of activity over a 24-hour period. “The horse sleeps in short cycles, an evolutionary advantage that helps them keep alert for attacks from predators,” says Murphy. Physiological functions, such as cortisol levels, platelet activity, lipid metabolism, and immune function are all controlled by peripheral clocks in the horse via a central pacemaker in the brain.

At a cellular level, these clocks consist of a set of genes that code for important proteins that regulate 24-hr rhythms in physiology, keeping the animal in synchrony with its environment. Murphy thinks that modern horse management may “mask” the horse’s natural tendency towards shorter ultradian activity cycles.

Understanding the horse’s biological clock at the molecular level can help guide horse management and training practices and inform new research that may help in the treatment of disease. For example, the horse has oscillating levels of hormones in fat tissue, which may have therapeutic value in treating diseases such as laminitis and elevated blood lipids.

It may be more effective to vaccinate at the time of day when the immune system is most active. Understanding the regulation of muscle physiology may provide valuable information about combating jet lag in horses that are expected to perform optimally in competitions after long intercontinental flights. Finally, understanding the effect of the clocks on muscle repair and performance might help trainers understand optimum times for exercise and rest.

Murphy, B.A. Chronobiology and the horse: Recent revelations and future directions. The Veterinary Journal (2009) doi:10.1016/j.tvjl.2009.04.013

© 2011 Nancy Zacks

There are a lot of things to consider when deciding to move a paper-based manual online. There are plenty of tools out there. Since the early 90′s when I first started doing online help, the products have matured. Still, when deciding to provide electronic manuals for your customers, the devil is in the details. Migrating content to an online format should be a carefully considered strategy that considers your content development process, from writing, to review, and finally to distribution. Here are some things to consider:

• Who are your writers? Do you have professional technical writers, or professionals who write? Professional writers have specialized knowledge about tools, whereas professionals who create documents as a “secondary” function may not be familiar with specialized authoring tools, or may not want to learn them.

• How will you gather comments from reviewers? Every technical documentation function has a review process where subject matter experts review content. Will your solution fit with your review process, or does it require that reviewers switch to new tools? For example, many people have learned the basics of Microsoft Word. Marketing professionals may prefer InDesign for page layout. Professional technical writers might be more familiar with Adobe FrameMaker.

• How often does your content change? The number of times you need to revise your documents will also affect the tool you choose. Does your documentation describe a mature product that requires only periodic updates, or are there likely to be numerous changes in marketing strategy and technical information?

• What is your legacy document situation? Many companies are tied to a specific content development application historical or business reasons. If you have decided that your online workflow must support a certain application, you need to consider tools that provide easy and accurate conversions. For example, if you must use Microsoft Word, consider Adobe RoboHelp, DocToHelp or Webworks Publisher. These products convert documents by mapping Microsoft Word styles to online styles. If you have the luxury of selecting your own tools and setting up your own process, you can start with tools that are specifically designed for single-source content development.

• What is your budget? There are many ways to publish online. Solutions can be as simple as publishing a PDF to your website. Don’t overlook the simplest things first. For example, if you want to publish a procedural document (where tasks must be done in order) a PDF might be best. PDF has basic table of contents and indexes. You can also opt to automate the entire process with a suite of tools that work together, such as products from MadCap Software.

• To what extent will you re-use your content? Companies that make technical products often use instructions in training materials, documentation, marketing, and within software applications. An XML-based content development and distribution system allows you to re-use components of your documentation for different purposes without keeping multiple copies.

• What are your printing requirements? Most content development tools create PDF. However, you may want to segment your process by document type. For example, a large software reference document might be a good candidate for an online manual, whereas a short laboratory protocol might be better as a PDF document.

• Do you need  version control? A variety of enterprise version control systems keep track of documents in a shared location for editing my multiple writers. This can be as simple as SVN for small development groups, or enterprise-wide, such as Documentum, which can be found in large technical publications departments.

• What is your company culture? Is your team familiar with the documentation development process? The best tools and processes will fail if team members do not understand the importance of documentation reviews. For example, companies that develop software as a primary product have integrated documentation into the engineering process. Companies whose products incorporate software (such as medical device companies) may not be familiar with documentation practices.

There are many more things to consider when adding online content development to your process. These questions should help get you started. The HAT (Help Authoring Tool) Matrix website is a good place to start to learn about some of the most popular help authoring tools. You can compare each tool, read reviews, and read about issues to consider when migrating content online. The vendors on this site pay to list their tools, but it covers the most common ones including Flare, RoboHelp, Author-It and Doc-To-Help.

Lilly, my two-year-old Lab developed cauliflower-like growths on her lip and inside her mouth. According to my veterinarian, and the Merck Veterinary Manual, these unwelcome growths are viral papillomas – otherwise known as warts. My veterinarian assured me that the warts are self-limiting (they will likely go away in a few months). I was relieved because they look quite dramatic — like small sea anemones.

I know that in humans, papillomaviruses are associated with cervical cancer³. I started to wonder; how can a papillomavirus be associated with benign warts in dogs, and a deadly cancer in women? Answering this question required some digging through the literature to find out more about canine oral papillomavirus (CoPV) and human papillomaviruses (HPV). What I found was only the tip of a very large research iceberg, but here are some of the interesting items…

• The papillomaviruses are species-specific (a dog papillomavirus cannot infect a human) yet there are some interesting similarities between the canine and human viruses:
• Both CoPV and HPV are mucosotropic (they create changes in the epithelial cell layer of mucous membranes).
• CoPV (also called CPV1) infects the dog’s lips and gums^{1, 2}. HPV infects the cervix in women.^{3, 4}
• Both viruses induce a change in squamous epithelial cells (the topmost layer of skin cells) that appears as a “halo” around the nucleus in the infected cells. In 1956, Koss and Durfee called these cells “koilocytes,” from the Greek “hollow cell.”⁴ Dr. Hang Yuan, a virologist at Georgetown University provides a micrograph of koilocytes in the dog epithelium. Here is an image of human koilocytes next to normal cells (left). Both have enlarged nuclei as compared to normal cells, and both show a “halo” (vacuolization) around the nucleus.

So… Why does a papillomavirus cause annoying warts in my dog, and a deadly cancer in women? It turns out that like much of science today, it seems that part of the answer lies on the molecular doings of the virus proteins. In a 2009 paper, Rachel Condjell et al., also of Georgetown University, examined another type of canine papillomavirus, CPV type 2 (CfPV2) . The CfPV2 virus is associated with warts on a dog’s footpads and does progress to cancer. CPV1 (the oral dog wart virus) rarely leads to cancer, yet CPV2 does. Why?

When comparing the genetic makeup of CPV1 with CfPV2, the researchers found that CPV1 (the oral dog wart virus) lacks E5, a protein that plays an important role in carcinogenesis. The CfPV2, type which is associated with warts on the footpads of dogs does have the gene that encodes for the E5 protein. The human papillomavirus (HPV) also has an E5 protein ¹ , the one that causes koilocytotic changes in human cells.

In both human and canine skin cells, the E5 protein alters the normal cell signaling pathways involved in normal cell growth. The protein induces koilocytosis (the halo around the nucleus) ^{1, 3, 4, 5, 6} and destabilizes the proteins required for normal growth. The E5 protein is also encoded by the HPV-16 gene, which has been identified with human cervical cancer ². This, of course is only a very small part of the story, but it shows what a difference a few molecules make, and how animal models are useful in understanding human disease.

References

1. Rachel Condjella, et al. The Canine Papillomavirus E5 Protein Signals from the Endoplasmic Reticulum. JOURNAL OF VIROLOGY, Dec. 2009, p. 12833–12841. Abstract. Vol. 83, No. 24 0022-538X/09/$12.00 doi:10.1128/JVI.01003-09
2. Campo. M Saveria. Animal Models of Papillomavirus Pathogenesis. Abstract. Virus Research. Vol. 89, No.2. P. 249-261. 2002.
3. Crum, Christopher P. MD. Contemporary Theories of Cervical Carcinogenesis: The virus, the host and the stem cell. The 1999 Long Course on Pathology of the Uterine Corpus and Cervix. The United States and Canadian Academy of Pathology, Inc. Vol 13, No. 3 P. 243. 2000.
4. Koss, LG, Durfee, GR. Unusual patterns of squamous epithelium of the uterine cervix: cytologic and koilocytotic atypia. Ann. NY Acad Sci. Vol. 30 No. 63. P. 1245-61. Available at: http://www.ncbi.nlm.nih.gov/pubmed/13314471.
   4. Yuan, H. COPV (CPV1) – Canine Papillomavirus and Vaccines. Available at: http://copv.info/2.html. Accessed April 21, 2011.
5. Hajdu, Steven I. A Note from History. The Link Between Koilocytes and Human Papillomaviruses. Annals of Clinical and Laboratory Science, vol. 36, no. 4 2006. Available online at www.anclinlabsci.org
6. Wang J. et al. PLoS Pathogens: The Canine Papillomavirus and Gamma HPV E7 Proteins Use an Alternative Domain to Bind and Destabilize the Retinoblastoma Protein. Available at: http://www.plospathogens.org/article/info%3Adoi%2F10.1371%2Fjournal.ppat.1001089. Accessed April 17, 2011.

http://www.ncbi.nlm.nih.gov/pubmed/10690928

As an equine journalist and technical writer, I’ve always wanted to see a large animal hospital. On May 11, I got my chance when I attended the Tufts Cummings School of Veterinary Medicine Faculty Speaker Series “The Athlete Horse: Running a Winning Equine Sports Medicine Program,” at the Tufts Cummings School of Veterinary Medicine. The presentation summarized the school’s veterinary services, including, respiratory performance evaluation, regenerative therapies, and diagnostic imaging. The talk took place on the beautiful Cummings School campus, with an added bonus – a tour of the Hospital for Large Animals on Westboro Road in North Grafton, MA.

Respiratory Performance. Although an old horseman’s adage says “no hoof, no horse,” top performance involves more than the musculoskeletal system, according to the first speaker, Melissa Mazan, DVM, DACVIM. Mazan studies equine inflammatory airway disease, which can affect performance in subtle ways such as non-specific “poor performance,” and not-so-subtle ways, such as that explosive cough that pulls a dressage rider out of the saddle. By summarizing the physiology of lung function and showing images of elevated levels of neutrophils as a sign of inflammation, Dr. Mazan illustrated the biological consequences of excessive levels of dust in the air. Dr. Mazan made us all think about the levels of dust in our barns. Finishing this sentence just made me sneeze!

Diagnostic Imaging for Equine Sports Medicine. As a neat transition, Jose Garcia-Lopez, VMD, DACVS summarized types of anatomical airway obstruction and surgical correction of the soft palate to increase the amount of oxygen that the horse can use when breathing hard. He showed before and after endoscopy videos of a soft palate that had been lifted to remove an airway obstruction. From there, Dr. Lopez summarized the various diagnostic imaging modalities and their uses, all with clear pictures and anatomical descriptions so we could see the advantages of each modality.

Regenerative Medicine, Ultrasound and Magnetic Shockwave Therapy. Kate Chope, VMD rounded out the lecture with a discussion of regenerative therapies IRAP (Interleukin-1 Receptor Antagonist Protein) and PRP (Platelet-rich Plasma). Dr. Chope is the hospital ultrasound specialist, and she showed us some wonderful images. Dr. Chope also summarized magnetic shockwave therapies for promoting healing and reducing pain in musculoskeletal injuries.

A Tour of the Hospital for Large Animals. The lectures were all well-illustrated, comprehensive, and clear. After the talks, we got a tour of the equine hospital including the equine recovery room, CT scanner, and treadmill room. Everyone in the audience had a different reason for wanting to see the hospital; there were horse owners, hospital clients, and curious neighbors. It was a wonderful opportunity to learn about equine sports medicine at Tufts.

More Information

Additional information about the Faculty Speaker Series

Tufts Cummings School of Veterinary Medicine