The SANS Technology Institute

Leadership Laboratory

What are the characteristics of a professional security technical writer?

December 4th, 2007
By Stephen Northcutt

According to Wikipedia, "Technical writers are professional writers who design, create, maintain and update many types of technical documentation, online help, user guides, white papers, design specifications, and other documents."[1] The US Department of Labor has a more in depth description, "Technical writers put technical information into easily understandable language. They prepare operating and maintenance manuals, catalogs, parts lists, assembly instructions, sales promotion materials, and project proposals. Many technical writers work with engineers on technical subject matters to prepare written interpretations of engineering and design specifications and other information for a general readership. Technical writers also may serve as part of a team conducting usability studies to help improve the design of a product that still is in the prototype stage. They plan and edit technical materials and oversee the preparation of illustrations, photographs, diagrams, and charts."[2] From our own experience we can expand that to include security policy, security awareness posters[5,6], press releases, blog posts, blog post comments and refutations, memos to management on technical issues, executive summaries of reports, technical analysis of news stories, courseware, help files, how-to's, and presentations.

Often, a technical writer must first research the topic they are writing about so strong research skills are also important. This ranges from power searching on Google[8], to knowing how to leverage expert sites such as the writers write.[9] There are more online resources than ever before, here are a few worth trying:

• Onelook has a reverse dictionary feature, if you can't think of a word, simply enter its definition and Onelook gives you a list.[10]
• Wordspy tries to track the new words being used in publications. Such things should be used sparingly, but when you are trying to establish a perception of being "with it" or when targeting a younger crowd, this can be helpful.[11]
• SANS Reading Room, contains the largest collection of security research papers on the Internet
• Argumentative Essays, a primer on argumentation (a persuasive research paper)
• Most colleges and universities provide students with a large number of research tools. As a writer, it may be worth considering taking courses to maintain access, or potentially working part time for an educational institution. For instance, here are the tools available to University of Washington students.[14]

If you are trying to hire a technical writer, expect to see people that want to be paid as much as, or more than system administrators or even software programmers. If you are trying to hire a technical writer, make sure there is an escape clause if things do not work out. Also, the interview process is very important. Job-Interview.net[15] lists the following as a few questions to ask a potential technical writer:

• How would you style a document to address a technical audience?
• Describe your experience with network infrastructures.
• Have you ever created any online help?

In general, organizations will favor readability and clarity over perfect grammar. In fact, the more technical the material is, the less important the grammar is while the ability to convey the thought to the reader accurately becomes very important. Nevertheless, correct spelling, avoiding the common errors of writing in English and compliance with the organization's style guide is crucial. Some useful web resources:

• Dictionary.com is becoming a very popular resource for checking the spelling and meaning of a word
• Standler's web site is a must read for every writer

How do you learn to be a technical writer? There are many programs, but the short answer is that you have to write, a lot, and your work needs to be reviewed by someone qualified to review technical security material. I have written several technical books, but the first book was the most important. I was blessed with a great developmental editor. Later in life, I worked with bad editors it wasn't that much of an issue since I was seasoned by that time, but it really helped me understand how important good review is to the writing process. Before you put your money down to learn to improve your technical writing, be certain that you understand the quality and quantity of review you can expect from the program.

All links harvested November 30, 2007
1. http://en.wikipedia.org/wiki/Technical_writer
2. http://www.bls.gov/oco/ocos089.htm
3. http://www.sans.org/resources/policies/
4. http://www.sans.org/resources/policies/
5. http://www.sans.edu/resources/student_projects/200711_003.pdf
6. http://www.sans.edu/resources/student_projects/200711_001.pdf
7. http://www.sans.org/press/
8. http://www.sans.edu/resources/leadershiplab/google_power_search.php
9. http://www.writerswrite.com/research/experts.htm
10. http://www.onelook.com/
11. http://www.wordspy.com/
12. http://www.sans.org/reading_room/
13. http://www.rscc.cc.tn.us/owl&writingcenter/OWL/Argument.html
14. http://library.uwb.edu/guides/css301/
15. http://www.job-interview.net/sample/TechnicalWriter.htm
16. http://dictionary.reference.com/
17. http://www.rbs0.com/tw.htm