Shelfware: How to Avoid =
Writing=20
Security Policy and Documentation That Doesn’t =
Work Abstract: "Shelfware" is an informal term for = documentation that is required, but will probably never be used = because=20 the intended users don’t find it helpful. Anyone who writes = security=20 policy documentation should ensure that the result is concise, = clear and=20 authoritative. This paper outlines a strategy for achieving that = goal, and=20 thus maximizing the chance that the intended users will actually = employ=20 the resulting product. This paper explores the "GIAC Basic = Security=20 Policy" material (Part V of the course), looking into pitfalls = that can=20 make security policy and similar documentation unwieldy and=20 unreadable. The Problem – = What is=20 shelfware? All too often, security policy and = similar=20 documentation becomes shelfware; that is, it fulfills the = organization’s=20 requirement that it have a policy, without achieving = acceptance as=20 a functional tool. So, if asked, the security manager can say, = "yes, I=20 have a security policy" (or contingency plan or incident response = plan,=20 etc.), "and there it is on my bookshelf." But when tasked with = making a=20 security decision or responding to a crisis, this manager will = rely on his=20 own expertise, rather than referring to the written=20 documentation. This problem is especially evident = in large=20 organizations, with standardized documentation requirements. In = the United=20 States Department of Defense (DoD), security documentation must = satisfy=20 the DoD Information Technology Security Certification and = Accreditation=20 Process (DITSCAP), which calls for a main document and eighteen=20 appendices. The result can be a daunting array of binders. If = nobody reads=20 them, essential information may be overlooked. Part of the solution to the = shelfware problem=20 is to make the information as focused and readable as possible. = But that=20 is a challenging assignment. According to a textbook description,=20 "Technical writing is more like investigative reporting than = scientific=20 writing, requiring practitioners to gather information rapidly, = identify=20 audiences, and use creativity and problem-solving skills." This is = unfamiliar work for many of the technical personnel involved in=20 information system security. Still, in order for the technical = message to=20 get through, technical writing skills must be applied. This paper proposes to solve the = problem by=20 focusing on just a few technical writing skills, those that are = required=20 to fix the worst readability problems commonly found in security = policy=20 documentation. The Strategy = – Employ selected=20 technical writing skills to improve security policy=20 documentation. Manage the = document=20 set. If your security policy will be a=20 multiple-document set (or a main document with a number of = appendices),=20 you should start by planning how you will manage the document set. = This=20 plan should include:
Table 1 = -=20 Documentation Set User’s Guide
Document planning is especially = important for=20 documentation efforts that are undertaken by a team. Whether your = project=20 is a team effort or a one-man show, you should plan on some give = and take.=20 The above planning elements will probably require adjustment as = the=20 project progresses and the result begins to take = shape. Do it with=20 style. Plan the style and tone of your = document, as=20 well as its organization. This is also important in a team effort, = where=20 writing styles differ. This doesn’t need to be an abstract = task, because=20 you can get good improvements in readability by focusing on just a = few=20 particularly troublesome areas:
Whatever your decision, be = consistent on=20 applying these throughout the document set. Focus on the = reader. Following your document plan, focus = on=20 different readers in different documents or sections. Identify the = anticipated readers before you write, then stay focused on that = audience=20 as you develop your subject. You may find it useful to identify = the=20 intended readers at the start of a document or appendix, but = it’s not=20 always necessary to be that explicit. In situations where material for = various=20 audiences supports a single task or topic, group the material by = audience=20 and clearly identify the groups. Paragraph headings work well for=20 this. Identify the consequences for = failure to follow=20 the policy, wherever you can. Even if you know that your current = reader is an=20 experienced professional who doesn’t need detailed = explanations, write at=20 the level of someone who is relatively new. Explain things as if = you were=20 writing for his replacement. Follow the=20 action. Focus on the problem at hand. For=20 action-oriented information (e.g., an Incident Response Plan) = present the=20 material compactly and emphasize the action. Don’t let = background=20 knowledge obstruct the flow and obscure the policy. Unless it is = very=20 short, separate background knowledge (such as why this is = the=20 policy) from the active elements. This kind of material should be=20 presented after the active elements, unless it is clearly required = to=20 understand the action. Keep it short! Think of the reader = who only=20 opens the reference to understand one element of policy or one = procedure …=20 the one you are writing now … and explain it as briefly and = directly as=20 possible. Add amplifying information and conditional = sub-procedures at the=20 end. Use topic sentences, as much as = possible. The=20 first paragraph of each paragraph should convey its main idea. Try = reading=20 just the first sentence from each paragraph, to check your flow = and=20 information content. Note that outline headings typically = don’t=20 convey complete ideas, so they don’t serve the same purpose. = Be careful = what you=20 borrow. If you use a security policy that = is already=20 developed, be careful in adapting it or integrating it with your = existing=20 material. A number of sources, including GIAC (as part of the = course) and=20 the Tech Republic web site offer security policies of various = kinds,=20 acceptable use policies, and so on. These are very useful, as = examples and=20 reminders (so you don’t forget anything). But they can cause = readability=20 problems too, especially if you borrow from more than one source. = Problems=20 include:
Borrowed material is rarely = suitable for=20 pasting in as-is; it usually requires a major editing effort to = overcome=20 the problems listed above. Make sure = that bulleted=20 lists have similar items, grammatically. Bulleted lists are a compact and = memorable way=20 to convey information, but they become less readable if the items = don’t=20 match, grammatically. Typically, the list is introduced by a = sentence=20 fragment, and each item in the list is an optional ending for it. = So, for=20 instance, if the list starts out as a list of nouns with = modifiers, it=20 shouldn’t have any items that are verb = phrases. Be rigorous = in using=20 categorizations. Categorization is a powerful tool = for breaking=20 down complex information. Unfortunately, sloppy construction of = category=20 sets often makes them confusing. Some common errors are:
Use the=20 technology. Use updated technology to get the = information=20 to readers in the most usable form. There are a number of = alternatives to=20 fat binders, although most organizations would prefer to = supplement,=20 rather than replace, their hard copies. For end users, consider providing = the User=20 Guide and other documents in the form of help files. These can = either be=20 Windows Help files, installed on the user’s computer, or = html Help files=20 available on a web page. Either way, you can offer a table of = contents,=20 index, and search feature that help users find the information = they need.=20 Of course, if their computer is down, they won’t be able to = read Help=20 files. But you can still offer the same material in a printed = manual, and=20 without the expense of starting over from scratch. Some help = authoring=20 software, such as eHelp, can readily export Help projects to print = (Microsoft Word) format. For System Administrators and other = managers,=20 consider providing reference material in electronic form, with a = search=20 engine that’s really makes the information accessible. = dtSearch makes a=20 product that can do Boolean searches, proximity searches, find = stemming=20 variations of words (e.g., find, finds, finding, etc.), use a = built-in=20 thesaurus, or let you build your own list of synonyms (such as = your=20 companies common abbreviations and acronyms); in short, a product = that=20 does much more than an ordinary word search. And it can either be=20 purchased as a desktop software application, or prepackaged with a = CD=20 containing the references themselves. A technological solution can be a=20 cost-effective enhancement, especially when the bulk of the policy = makes=20 it difficult to handle in paper form. The Result - Readable security = policy=20 documentation is more likely to be used. When documentation is focused, = concise and=20 readable, it has a good chance of being accepted as a functional = tool and=20 thus achieving its purpose. Sources Cited AltaVista (n.d.). Art of technical=20
documentation [WWW page]. Department of Defense (2000). =
Department of=20
Defense manual number 8510.1-M: Department of Defense information=20
technology security certification and accreditation process =
(DITSCAP)=20
application manual [downloadable file]. dtSearch (2000). dtSearch Corp. =
corporate and=20
product information [WWW page]. eHelp (1999). Demystifying help=20
[White paper]. Irish, R. K., & Kwiatek, D. =
(1999).=20
Engineering Writing Centre – handbook – outlines =
[WWW page].=20
TechRepublic (n.d.). Search results =
– Tech=20
Republic [WWW page]. |
|||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||
|