Document Structure
This section provides an overview of the possible document configurations including some advantages and disadvantages to both. Following are setup configurations that have been envisioned.
One Document that Describes the Entire Set
• Advantages. One document is typically easier to maintain and share. Also, the user only needs to configure the external link for the overall RPL set, not for each individual RPL object within the set.
• Disadvantages. Unless the viewing document is HTML, there is no way for the user to automatically open the document to the correct location. For example, if the user selects to view a rule document (say in PDF) they must still search for that rule within the PDF document. Also, multiple model users have to coordinate if they wish to develop documentation simultaneously.
One Document for Each RPL Object in the Set
• Advantages. One document for each RPL object allows the user to easily view the external document specific to that object. For example, the user selects the View button for a rule and the document specific to that rule opens. Multiple users can more easily develop documentation simultaneously.
• Disadvantage. It is more time consuming to configure and maintain. When sharing, there are many more documents to pass around. If there are a large number of RPL objects, there will be a large number of documents.
Multiple Documents With One for Each Policy and Utility Group
This structure is a hybrid of the two above and has some of the advantages and disadvantages of both. This structure is useful because exceptions to the overall scheme are natural. For example, most of the set could be described by one document, while special objects could be described in a document of their own.
Combinations of the above could be envisioned. The choice of the structure to use depends on the format and the end use.
Separate View and Edit Documents
External documentation for a single object might also be found in two different files, one for editing and one for viewing. For example, documentation might be created in MS Word, saved in Word format for the purposes of future edits, and also saved to a PDF file for the purpose of viewing. Thus the utility allows the user to specify two locations, one for the purposes of viewing and another for editing. Figure 4.1 shows an example as two separate documents, one for viewing, one for editing.
Figure 4.1
When the documentation for an object is split across many files, then it will often be convenient to the users for all the files to be located in the same directory. This organization is supported without requiring the user to provide redundant information (i.e., repeat the full path to the documentation for each object in the ruleset). At the same time, there is enough flexibility so as not to impose a specific organization on the documentation, either that there be a one-to-one correspondence between ruleset objects and documents or that multiple documents appear in the same directory.
Revised: 11/11/2019