How to Improve a Handbook?

Recently I’ve been working on the Secure Development Handbook, the most important part of this website. So here I'll ask the author’s question. How do we improve it?



We know from our research that the contents of the handbook are valuable. They are a reasonable subset of the activities that are most effective and least cost to help a software development team with security. There will be others; but we know that these activities work well. What we cannot tell is how effective the handbook itself is at conveying how to do them to its target audience.


Writing a web handbook is interesting. It’s much more interactive than a printed book; we can publish early versions, solicit feedback, and use them to produce better versions: it’s ‘agile writing’. That benefits people earlier, and leads ultimately to a better book. 


The trick, though, is getting that feedback. One can solicit feedback, but one cannot command it. 


So what kinds of things might encourage people to help? There are a several possible approaches involving people directly. First there is the old standby, the writers workshop, particularly if we can get a team of constructive critics together. Next is soliciting critical feedback from colleagues, in the form of emails or scribbles on printed versions. Given, too, that the handbook is a tool to influence people, we might even do usability and impact testing: give pages to people to read and observe their reactions.


Finally, there are comments from people who read arbitrarily, and the handbook is set up to solicit those comments – so far without success. For supporting comment is one thing; generating the discussion is quite another. So, what might encourage helpful arbitrary feedback? 


The most obvious is simple; getting friends and colleagues to ‘prime the pump’, putting their comments in to encourage others. Other options are posting to existing discussion groups like LinkedIn, and requesting comment; or asking feedback from people on email lists.


Well, that’s a few approaches I’ll be using. Expect to hear from me soon!


- Charles


Photo credit: