Chapter 24: Writing Security Documentation and Error Messages

Chapter 24

Writing Security Documentation and Error Messages

This chapter is sorely needed and is the outcome of work by many documentation experts in various product groups at Microsoft. The chapter is divided into two main parts: security issues in documentation and security issues in error messages. I'm placing the two topics in one chapter because documentation people tend to have input for the text that goes into error messages. Generally, the really bad error messages are those created by developers with no input from user assistance or user education people!

Remember that product design is a process of negotiation and compromise. Security is just one of many factors considered when designing a product, along with ease of deployment, ease of use, manageability, stability, performance, feature set, legacy compatibility, cost and feasibility of implementation, production schedule, and more. The resulting compromises create scenarios in which security will be an issue, and it falls squarely on the documentation people to make sure users understand these trade-offs.