Technical Writing for Software Developers

3

Language and the Fundamental Mechanics of Explaining

How often have you read documentation to be left uncertain if the recommendations or details you read are what you should follow? It may have contained plenty of technical details and code examples that you thought were relevant to you, but you were left unclear on which to implement and how.

These are likely relevant criticisms of any documentation. As we all know, documentation is hard. What I mean is, did you trust it? Were you confident in what it said? Did you believe what it said was as correct as possible, all caveats aside? Chapter 2 covered the different types of documentation you might need to produce. This chapter looks at ensuring that all the words you fill that documentation ...