Post History

Source: https://writers.stackexchange.com/a/47796
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/47796
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Every propositional document (that is, one that is not telling a story) consists of three parts: the conclusion, the argument, and the evidence. The native or intuitive way that most people write such a document is to mix in bits of evidence as they develop the argument and then sprinkle bits of conclusions around as each part of the argument is concluded. The problem with this organization is that the reader has to read the whole thing even if they are only interested in parts of it.

For instance, some readers are only interested in the conclusions. For a design document, it is not their job to question the design but to implement it. They are not interested in the justification of the design or the user research data that supports the justification, they just want to know what to build.

Other people may be interested in the justification of the design decisions without wanting to dig deep into the data. They may trust that the data is what you say it is, but disagree on what to do about it. For instance, they may agree that feature X is wanted by customers but may feel it is not cost justified.

To accommodate these various reader needs, you can clearly separate out the conclusions, arguments, and evidence. There are different ways to do this that might be appropriate for different sets of audiences. For example, it is not uncommon to place most of the data in support of an argument in an appendix and just cite the top line numbers in the argument portion of the paper. It is also common to create an executive summary that just states the conclusions with only the most cursory mention of arguments or data.

There is no one template for this that is guaranteed to work in all cases. Instead, you have to figure out a design that will work for the particular set of readers you have. I call this a theory of use for the document I am about to write. The theory of use lays out my who each of the audiences is, why they are reading the document, what they are trying to do, and what information they will need to accomplish that task. If appropriate, I get the theory of use reviewed and signed off before I start work on the main document. Whether you use such a formal process or not, however, you should always have a theory of use in mind before writing any document.

Original score: 1