Post History

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

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

1. If you're working in a group, check the level of detail of existing documentation, and ask for guidance from your group leader, or a co-worker who seems to know what's what.

2. Picture an imaginary reader. Write a description of this ideal reader -- why is s/he reading your documentation, and what does s/he hope to get out of it? For example, you need to have clear in your mind whether the reader wants to simply _use_ your software, or whether s/he wants to be able to _modify_ it.

3. Perhaps you could provide two levels of detail. Analogy 1: Newspaper articles start with the very short version of the story, and then tell the longer version. Analogy 2: Eurogames often come with a short quick-start sheet, which skips the motivation and lovely prose, and just gives you a quick rundown of the set-up (preparation for play) and a bulleted list of the mechanics. A longer booklet can provide the story behind the game, a slow introduction to the pieces, tiles, etc. that one manipulates, notes about strategy and variants, and fine points about rules, etc.

4. Imagine that an editor writes to you and asks what the purpose of your article is, and why you took the approach you took. Write back to this imaginary editor. You'll probably find that writing about what you're trying to accomplish with your writing will help bring the project into better focus.

Original score: 1