Peer Reviews Improve Your Writin 9 by G a r y M. A b s h i r e So, you labored to meet all those u n r e a l i s t i c dates caused by an a c c e l e r a t e d schedule. You sweated over that tough writing assignment. You may feel that your d o c u m e n t is well written, but is it? Will a reader spot flaws that somehow you overlooked? R e g a r d l e s s of whether you're a f r e e - l a n c e writer, the only fully paid writer e m p l o y e d by a small company, just o n e of m a n y writers in a large p u b l i c a t i o n group, or some other kind of writer, you should still have one or m o r e peer reviews before your m a t e r i a l is published. A peer review of your writing will make you a better writer. However, if you are a free-lance writer or a o n e - p e r s o n writing staff, you may have difficulty getting a peer to look at what you have written, e s p e c i a l l y before it's published. Still, you Should get someone else to see if any o m i s s i o n s or loopholes remain. This person acts as a surrogate reader who h o p e f u l l y can m a k e intelligent guesses as to how well your "average" reader will be able to understand your writing. This person should also be able to spot technical inaccuracies as well as g r a m m a t i c a l mistakes. If you are part of a large writing staff, you should p r o b a b l y have three reviews from three d i f f e r e n t peer groups. The first r e v i e w is done by your editor, the second is done by the s u p p l i e r s of your information, and the third is done p r e d o m i n a n t l y by your cowriters. C o n s i d e r how these reviews could fit into a typical writing cycle for a large document. You o u t l i n e the document, write and rewrite the "first" draft, get an editor's review, incorporate all fitting suggestions, get a technical review from the technical experts, incorporate all a p p r o p r i a t e comments, get another w r i t e r ' s review, incorporate all w o r t h w h i l e advice, put finishing touches on your document, and finally send it off to the printer. The first peer review is with your editor. H a v e your editor examine your d o c u m e n t for greater c l a r i t y and proper grammar. Sometimes a better approach and a better organization is suggested. The best working a r r a n g e m e n t is one in which your editor wants only to share ideas. T h e final d e c i s i o n to use some or all of these ideas rests with you. After all, your p r i m a r y reason for writing should be to please yourself and your reader. The second peer review is with the people who gave you your source information. H a v e them review your d o c u m e n t for technical a c c u r a c y and completeness. H a v e them comment on its usefulness and organization, have them suggest additions and deletions, and have them note any errors or omissions. E n c o u r a g e them to be specific. As you know, c o m m e n t s such as "doesn't work that way," "not true," "incorrect," "not in all cases," or "needs c l a r i f i c a t i o n " are not always helpful. Therefore, tell them to indicate to you how it does work, what is true, what is correct, in what cases it does apply, or what c l a r i f i cation is needed. Have them mark their comments and c o r r e c t i o n s on the m a n u s c r i p t and return the o r i g i n a l s of their c o m m e n t s to you on a given date. T e l l them that if you do not receive their comments on that date, you will assume that they have no major c o n c e r n s with your d o c u m e n t and that they tacitly approve it for publication. Keep their comments for the "life" of the subject you are w r i t i n g about. The third peer review is p r e d o m i n a n t l y with your co-writers. Pick a person, other than yourself, to p r e s i d e over the r e v i e w meeting. You should attend only as an observer. C h o o s e the p a r t i c i p a n t s and notify them in time to allow them to s c r u t i n i z e the d o c u m e n t in question. The p a r t i c i p a n t s should include at least your editor, three other writers, a graphics expert, and a technical p e r s o n familiar with the m a t e r i a l to be reviewed. H a v e them examine the most recent p a s t e d - u p copy of your d o c u m e n t and request that they advise you on how to polish it. Supervisors and m a n a g e r s should not attend this review, because of p o s s i b l e intimidation. Likewise, the results of this review should not be given to any supervisor or manager, because of p o s s i b l e recrimination. If you follow these suggestions, you will have three peer reviews for all of your writing. For best results, tailor them to your own job situation. Remember, the m o r e people who read your writing before it is published, the better your writing will be. WHY AN A L G O R I T H M I C D O C U M E N T A T I O N Robert F a u l k n e r LANGUAGE C o m p u t e r Systems Branch A S D Front End Systems Dep't Texas Instruments, Inc. ABSTRACT System designers have tried multiple techniques for documenting what a program does, from "Self Documenting" languages to Flow Charts. The d i f f i c u l t y is that "Self Documenting" languages aren't and flow charts are difficult to maintain, plus neither g e n e r a l l y follows the way in which programs are really designed. An Algorithmic

/lp/association-for-computing-machinery/peer-reviews-improve-your-writing-uqM5aFvLxX