Lets try to get a subject on this stuff okay?
I like manuals organised so the student is be able to start at the beginning and learn things in sequence like a good book. :-)My preference is to lay out the info by process flow.
Right. I would add that when I described how I wanted the manual written in the past, I have favored clearly separating the "what" and the "how" in the election process. This could be done with two manuals or by interleaved chapters. I have seen both approaches in documentation before, although I favor the former.
A good example of this would be for the setup of counting and reporting. It is difficult users to follow a single "process flow" for this as there are many ways to set up counting, and reporting is dependent on this setup. That is, there is no single process to walk the user though. Typically during training the student is just walked through the relevant procedure, but it is not that simple when it comes to written docs. Of course, new support staff that read the documentation will need to see the whole picture.
One way to accomplish this with documentation is to write a chapter describing the various ways in which jurisdictions organize their counters and reports, ranging from very simple Florida to raging lunatic Tulare. For example, it might describe *what* combined absentee reporting is, entirely independent of *how* setting it up would be accomplished in GEMS. This description would be useful even if GEMS procedures were to change, would be useful in understanding how our legacy election software works (VTS and Precinct Manager), and would be useful in training new support staff and customers in election organization and procedure.
Once a basis for the what is established, it is much easier to describe the how. For example, you can then describe the procedure for setting up combined absentee reporting. If the user already knows what that means (or have read enough to know it doesn't apply to them), then the description of how to set that up in GEMS becomes a lot more clear, or easy to skip over.
The same thing goes for other tough topics like district organization, multiple-precinct vote centers, rotation, multiple voter groups, tally rule options, ballot generation including sequence numbers, etc etc etc.
I also suggest assuming less election experience rather than more. It is usually true that the reader of the documentation will have at least some election experience for their jurisdiction, but this does not help readers who for ever reason do not have much experience, or are required to know election concepts for the whole country (such as our support staff).
I favor this what/how based approach over the alternative, which is kind of a "flow-chart" driven model. For example "If you use combined absentee precincts, which means so-and-so, skip to page 34, else if you report absentees by precinct, which means so-and-so, skip to page 50, and so on". Given the number of ways in which elections are conducted, this very quickly becomes unwieldy.
Ken