How to Improve a Handbook?

 

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: https://www.flickr.com/photos/gforsythe/10173857405