From GridLAB-D Wiki
Jump to: navigation, search

 

This guide is to assist those writing documentation for GridLAB-D so that a certain degree of consistency can be maintained. It is divided into different sections according to the type of documentation being written.

General Guidelines

GridLAB-D documentation is divided into major categories. With the exception of User Manuals each type of document should use a prefixed name to identify what the type of document is, e.g., Req:topic.

Documents that are actively being worked on must use heading templates to aid in searching and identification. The {{NAVIGATION}} template should always be placed at the top every working document. The template appears as follows

Use Cases Requirements Specifications Implementations Validation Training Index

In addition, each class of working document must use the following working templates placed at the beginning of every section being worked on or immediately after the navigation template if the entire document is active.

  • {{USECASE}} Use cases
  • {{REQUIREMENT}} Requirements
  • {{SPECIFICATION}} Specifications
  • {{IMPLEMENTATION}} Technical support documents
  • {{VALIDATION}} Validation test plans
  • {{TRAINING}} Training materials
  • [[Index]] The main index

Tables of Contents

Use of the __TOC__ is discouraged for most manuals because a good Synopsis section provides the same features in a manner that is better suited to the subject of the page. For this reason, every page that has a Synopsis should use __NOTOC__ on the first line or on the line before the Synopsis heading.

For pages that do not use a Synopsis heading, the {{TOC}} template should be used to ensure that all document use the same contents style (e.g., floating right).

Markings

Template tags are used to mark the status of pages. Pages without markings are of unknown status and will be reviewed periodically to determine their status and marked accordingly.

{{PROPOSED}}

When a page proposes a new concept, feature, or capability, it should be marked with the {{PROPOSED}} tag to indicate that input is sought from the GridLAB-D community.

{{WORKING}}

When a page is being edited or worked on and is not yet ready for review, it should be marked with the {{WORKING}} tag to indicate it's status as a work in progress.

{{REVIEW}}

When a page is ready for review, is should be marked with the {{REVIEW}} tag to indicate that reviewers are invited to contribute to discussions needed to finalize the page.

{{APPROVAL}}

When the review of a page is completed and the document changes are ready for approval, the approval template {{APPROVAL}} should be used and placed after the working template to help project managers find approval items. The approval request should be signed by the responsible author using signature code --~~~~.

{{APPROVED}}

When the document is approved, the {{APPROVED}} is used. Note that this template does not display anything in the document itself and is simply used for searching purposes.

Version markings

New features introduced in a particular version should be marked with the template {{NEW##}} to indicate which version it applies to. Such markings will eventually be removed by making the template empty when the version indicated becomes obsolete.

Version references

Rather than referring to a version explicitly, which can required periodic extensive changes throughout the Wiki pages), we strongly encourage authors to define and use the following version templates.

{{VERSION##}}
This template is used to refer to a specific version by name and numbers, e.g. {{VERSION10}} is Allston (Version 1.0) . This also conveniently embeds a link to the documentation page for that version.
{{STABLE}}
This template always refers to the current stable version, e.g., Navajo (Version 4.3).
{{NEXTRC}}
This template always refers to the next release candidate version, e.g., Ostrander (Version 5.0).
{{TRUNK}}
This template always refers to the development trunk version, e.g., Navajo (trunk).

You can link to a specific changeset in TRAC using the {{CHANGESET}}/revnum template. The same works for references to tickets using the {{TICKET}}/id template.

Talk Pages

Discussions should be conducted on the Talk pages provided for each page. Discussion is relatively freeform, but here are some helpful suggestions:

  • Reviewers should be grouped under a brief topic heading using the ; topic : comment format. Both the topic and the command should be very succinct. Long narrative and stream of thought comments are not conducive to getting something done. This is also not the place to pontificate or expounds of general theory. Citations and external links to additional helpful information are welcome and helpful.
  • Do not provide comments by email unless they are not meant for public consumption. Similarly, do not post private and proprietary content. Remember, everything posted on these pages is subject to the Terms of Use.
  • Always sign and date comments and responses using the --~~~~ tag.
  • Responses to comments should be placed reverse chronologic order (newest first) as bullets under the topic item.
  • When the comment is satisfactorily addressed or it is determined that it will not be addressed it should be moved to == Closed == section of the Talk page with a brief explanation of the disposition and reason.
  • If a comment is deferred it should be moved to a == Deferred == section of the Talk page with a brief explanation.
  • If you want to monitoring ongoing activity on the Talk page, use the Watch feature.

User Manuals

User Manuals give GridLAB-D users important information for creating simulation models and using GridLAB-D in an extremely clear and concise form. Long narrative discussions and theoretical developments are inappropriate.

User manuals are designed to be easily linked to and searched from an external user interface systems, such as a web browser. Consequently, with few exceptions the page names must always be one keyword (two at most if disambiguation is necessary). When two keywords are used, the second should be parenthetical and relate to the category it addresses, e.g.,

object (directive) describes the object directive.

object (property) describes the object property.

The foundation of the User Manuals is the Index which must be carefully maintained. The index is alphabetical. When several different topics fall under a particular category, the topic must be disambiguated in subtopics, e.g.,

  • Object
    • Directive
    • Property

Each page must address just one topic and do so as completely as possible. The first line should provide the name of the item (usually the name of the page) and a one-line brief description, e.g.,

[[topic]] - Brief description of topic

followed by a synopsis, e.g.,

Synopsis

[[topic]] {options, etc.}

and the narrative sections. Each section must address one subtopic. In general, after the opening paragraphs explaining the topic, subtopics should be included to address the following as appropriate

GLM
The GLM subtopic is required for all topics that relate to content that would be found in a GLM file.
Properties
The Properties subtopic is required for all topics that relate to the description of a class.
Command line
The Command line subtopic is required for all topics that related to the description of command line options.

Additional section may be provided as appropriate, e.g.,

Examples
Although examples are often provided in the subtopic, a separate subtopic can be included to provide more examples.
Testing
Some topics, most notable modules and classes often contain discussion of testing and validation.
Bugs
If significant issues are known, they can be identified here.
History
A discussion of the history of the topic is particularly appropriate if there have been major changes over time.
Version
A brief note about which features are supported in which version is often helpful to user.
See also
The See also section is almost always required. Many pages can be grouped using a Xref template, i.e., {{:Xref:topic}}.

Often it is necessary to include the __NOTOC__ directive on the first line to suppress the automatic table of contents generation.

We strongly recommend using second level headings for the main headings of manuals because the formatting of the page title is the same as the first level heading.

How To Pages

A special type of manual called a How To is available. These pages must be named using the HowTo:topic prefix naming convention and include the {{HOWTO}} tag to facilitate searching using the How To template. In other respects How To pages are similar to User Manuals.

Instructional Guides

 TODO:  Instructional guide are dividing into lessons following the course materials distributed with the source code. Courses are divided into lessons, examples, exercises, and solutions. Each type of document is identified with the following prefixes:

Course
These documents mark the beginning of courses.
Lesson
These documents mark the lessons within each course.
Example
These documents provide the examples used with lessons.
Exercises
These documents provide the exercises at the end of each lesson.
Solution
These documents provide the solution to exercises.

Development

Develop documents are identified by the following prefixes:

  • Req : The "Req:" prefix is used to identify requirements documentation.
  • Spec : The "Spec:" prefix is used to identify specification documentation.
  • Tech : The "Tech:" prefix is used to identify technical support documentation.
  • Dev : The "Dev:" prefix is used to identify developer support documentation.

Requirements

Requirements documents describe what is necessary in the implementation of particular functionality in GridLAB-D. Requirements do not address how the implementation is to be accomplished, rather it addresses what users expect from it.

The language of requirements shall be enumerated, referenceable, prescriptive, verifiable and unambiguous. This is accomplished by observing the following:

Each distinct requirement shall be placed in an outline numbered section, e.g., R1, R1.1.
In particular subsections always provide more detailed requirements for the section they are within and do not span topics covered in other sections. Sections correspond to requirements and not topics or areas.
Each requirement shall use prescriptive language, e.g., shall instead of must, should, or may.
The use of prescriptive language is intended to force disambiguation and eliminate uncertainty later on.
Each requirement shall use definite constraints or bounds, e.g., no fewer than 12, instead of several or many.
In cases where a constraint is unbounded, state explicitly how the bound is related to other physical limits, e.g., available memory of the host computer.
Each requirement shall be stated as a positive verifiable requirement that can be tested.
"Negative or unverifiable requirements shall not be used" is not the preferred statement of a requirement.
Requirement numbers shall be used only once for a requirement and shall not be reassigned if the requirement is eliminated.
If a requirement is no longer required it is struck out using the <strike>delete this</strike> markup.

For more information on writing good requirements, see NASA Systems Engineering Handbook Appendix C. (Note that we do not endorse or encourage using the entire NASA systems engineering model for GridLAB-D development, but only those elements that seem to be effective in managing the complexity of the process.)

When substantive changes to requirements they must be submitted for review and approval.

Review
New documents are submitted for review by added a reference to the {{REVIEW}} template at the top of the document. Revised documents (i.e., the rest of the document is already approved as resubmitted for review by placing the {{REVIEW}} reference at the top of the section that was modified. When the review is complete the changes can be submitted for approval.
Approval
After review is complete, the document or revisions are submitted for approval by added a reference to the {{APPROVAL}} template in front of the affected content.

Specifications

Specifications documents pick up where requirements leave off. The documents address how the implementation of a particular functionality is to be achieved.

All substantive changes to specifications must be submitted for approval. This is done by adding a signed reference to the { { APPROVAL } } template in front of the content that is modified.


 TODO:  more on writing Spec: document is needed.

Technical Support Documents

Technical support documents provide detailed technical explanation for how a particular functionality is achieved. The technical support documents are designed to give users an insight into what is happening inside the software without exposing them to the mechanics of the software itself. Often, these documents will focus on the formulas and equations used to compute a solution.

 TODO:  more on writing Tech: documents is needed.

Developer Documentation

Most developer documentation is used to explain how widely used technical tools in GridLAB-D work and are used. The rest of the developer documentation is handled by the Doxygen system. Links to the Doxygen files are established using the {{DOXY???}} templates. Each version has its own Doxygen output which is maintained at

 http://www.gridlabd.org/documents/doxygen/major.minor/index.html

The templates {{DOXYVmn}} are used to reference major version m and minor version n. Additionally, the template {{DOXYREL}} references the last stable release, {{DOXYRC}} the current release candidate, and {{DOXYDEV}} the current trunk version.

To enable doxygen parsing of source files, you must include the following in the opening comments of the source file:

/** $Id$
 ** Copyright (C) year, author
 ** @file class.cpp
 ** @addtogroup module_name Module name
 ** @{
 **/ 

The last line in the file should be

/** @} **/

The /** and /// comment openings are critical to enabling Doxygen parsing. If you do not use these, doxygen will ignore the comment flags.

To document a function or a class, simply precede it with a brief comment:

/** My class
 **
 ** Detailed description goes here
 **/

or

/** My function
 ** 
 ** Detailed description goes here
 **
 ** @returns my data
 ** @see references
 **/

To document members and arguments, simply follow each one with the comment

/// My function
/// Detailed description
/// @returns return specs
void my_function(int arg1, ///< argument 1 specs
                 int arg2) ///< argument 2 specs
{
}

Process Management

The following process is used to introduce, define, implement, and validate changes to GridLAB-D:

Development process.png

(Note: this image was created using http://www.websequencediagrams.com/ and the input to it is kept at uml_process).

Actors

The following actors are recognized and have the indicated roles, responsibility, accountabilities and authorities. Accountability is also shown in Fig. 1.

Fig. 1 - Accountability Tree
Users
|
Sponsors
|
General Manager (GM)
|
|
Project Manager (PM)
|
|
Tester
|
Builder
|
Instructor
|
Designer
|
Coder
|
Documenter


Users
(Role) Users use GridLAB-D for the purpose of doing Smart Grid modeling and analysis. (Responsibility) Users are responsible for identifying work areas, describing the applications of GridLAB-D, and approving requirements. (Accountability) Users are accountable to their customers. (Authority) Users have the authority to initiate Work Areas, identify Application Concepts, and approve Requirements.
Sponsors
(Role) Sponsors fund the development and use of GridLAB-D. (Responsibility) Sponsors are responsible for approving Work Areas and approving the Annual Plan. (Accountability) Sponsors are accountable to Users for the funding and delivery of the needed applications. (Authority) Sponsors have the authority to control the budget, approve Work Areas and approving Annual Plans. The Sponsors have the authority to selected the General Manager with the advice and consent of the Users.
General Manager
(Role) The GM provides overall coordination of all GridLAB-D development activities. (Responsibility) The GM is responsible for developing the Annual Plan and overseeing the progress of all GridLAB-D development activities. (Accountability) The GM is accountable to the Sponsors for the delivery of all GridLAB-D releases. (Authority) The GM has the authority to control the schedule in consultation with the Sponsors and Users, manage spending, set policies and defines work breakdown structures needed to ensure delivery of required releases. The GM has the authority to select PMs with the advice and consent of the Sponsors and may delegate authority to PMs as needed.
Project Manager
(Role) PMs manage one or more GridLAB-D releases. (Responsibility) The PMs are responsible for the management of delivery of releases. PMs control the scope of each release in consultation with the GM, Sponsors, and Users. (Accountability) The PMs are accountable directly to the GM, and indirectly to the Sponsors and Users. (Authority) The PMs have the authority to select designers, coders, documenters, testers, and builders with the advice and consent of the GM, recommend scope change to remain within schedule and budget, and control the delivery of the release.
Designer
(Role) Designers design GridLAB-D releases by creating and maintaining Requirement and Specifications. (Responsibility) Designers are responsible for the delivery of the requirements and specifications of GridLAB-D releases in conformance with the project's standards and conventions. (Accountability) Designers are accountable to the PMs to ensure that the scope of the release as required and specified fits the budget and schedule defined. Designers are accountable to the Users to ensure that the scope of the release as required and specified satisfies the stated needs of the Users. (Authority) Designers have the authority to control the detailed requirements and specifications.
Coder
(Role) Coders implement GridLAB-D release. (Responsibility) Coders are responsible for software coding, software documentation and bug fixes in conformance with the project's standards and conventions. (Accountability) Coders are accountable to the PMs. (Authority) Coders have the authority to create and control the source code and its documentation.
Documenter
(Role) Documenters create and maintain the Documentation of GridLAB-D. (Responsibility) The are responsible for the content, accuracy, and quality of the Documentation in conformance with the project's standards and conventions. (Accountability) Documenters are accountable to the PMs for the delivery of the Documentation of each GridLAb-D release. (Authority) Documenters have the authority to control the content of the Documentation.
Tester
(Role) The Testers verify the functionality of GridLAB-D releases (Responsibility) Testers are responsible for ensuring that GridLAB-D releases satisfy the Requirements and meet the Specifications, for the development of Test Plan, creation and maintenance of the validation tools, applying the validation process, and reporting problems found as a result of running validation tests. (Accountability) Testers are accountable to the GM. (Authority) Testers have the authority to recommend approval of a build for release.
Builder
(Role) Builders compile and upload nightly builds, release candidates, and stable releases of GridLAB-D. (Responsibility) Buildings are responsible for maintaining and regularly the processes that builds GridLAB-D release in conformance with the project's standards and conventions. (Accountability) Builders are accountable to the GM. (Authority) Builders have the authority to control the build and release process.
Instructors
(Role) Instructors teach Users how to use GridLAB-D releases. (Responsibility) Instructors are responsible for the content and delivery training materials. (Accountability) Instructors are accountable to PMs. (Authority) Instructors have the authority to control the content and schedule of training courses.

Processes

Approval
Various products are subject to review and approval by those to whom actors are accountable. Product subject to review and approval are
  1. Work areas (Users → Sponsors♦ → GM)
  2. Annual plan (GM → Sponsors♦ → GM→ PM)
  3. Requirements (Designer → Users ♦→ Designer)
  4. Build release (Builder → Tester ♦→ Users)
Review
Specifications and Test Plans are approved by the Technical Manager in consultation with the Project Manager.
Coding
Coding is performed by developers according to the Specifications.
Documentation
Documentation is performed by designers, coders, and documenters.
Testing
Testing and validation is performed by testers.
Instructor
Training is performed by Instructors.

Products

The following products are recognized:

Use Cases
Use cases are optional, but very helpful for if the requirements are expected to be very complex. Use cases are a non-technical description of scenarios for how GridLAB-D users are expected to use a feature or capability. Use cases are written by task managers in consultation with prospective users.
Requirements
Requirements are documents that precisely explain in quasi-technical terms what capabilities or features are needed. They generally enumerate what is needed. Requirements are generally written by task managers in consultation with technical teams and prospective users. At best it only roughly outlines how it is to be done, and then only from a user's perspective. Requirements are generally written in prescriptive language (e.g., "shall" rather than "should") and provide only quantitative and verifiable statements (e.g., 1000 rather than "many"). All requirement are subject to GridLAB-D project management review approval before being used to develop Specifications and Test plans.
Specifications
Specification are document that precisely describe in technical terms how Requirements are to be satisfied. Specifications are written by technical teams under the supervision of task managers. They are presented in highly technical prescriptive language by GridLAB-D's software designers and subject to technical manager review before be delivered to Coding, User Manual, and Autotest Case development.
Test Plans
Test plans document how the Requirements will be verified after coding is completed. Test plans describe two general types of tests: a) autotests, which are coded into the build system, and b) validation tests, which are manually conducted by testing users. Test plans are reviewed by the technical managers before being user to develop Autotest Cases and validation plans.
Source docs
Source documentation is generated automatically from special comments embedded in the source code by developers. The tool used to generate source document is Doxygen and the source documents are automatically posted by the build process online at the GridLAB-D website.
Autotest cases
The Autotest Cases are generated by developers (not the same ones as those who wrote the source code) and run as a part of the build process. Autotest Cases are given special names to identify what capability they are verifying, the manner in which the capability must be tested, and the disposition of the build based on the outcome of the test. Autotest that detect coding errors are usually addressed immediate with a code fix without being submitted as a Bug Report. However, any Autotest failures that require changes to Requirements, Specifications, Test plans, or Autotest Cases must be submitted as Bug Reports so that they can be dispatched appropriate and the resulting changes can be reviewed before being implemented.
Validation plans
Validation plans describe what user-based testing is intended to verify and how it is conducted. Validation plans are delivered to testing teams who conduct manual tests to verify that GridLAB-D is working as required.
User Manuals
User Manuals are on-line documents located on the SourceForge MediaWiki page. All User Manuals must be entered on the Index using a single (or paired) keyword. A second parenthetic term may be included for purposes of disambiguation. In addition, the Help:Contents section provides a topical overview all the User Manuals to help users get oriented.
Bug Reports
Bug Reports are entered in the TRAC system. All Bug Reports are review by the Technical Management team to determine the correct disposition of the report.

See also

Appendix A - Current Templates

The following template may be used in documents using {{TEMPLATE}} syntax.

Appendix B - Current Requirements Documents

Appendix C - Current Specifications Documents

Appendix D - Current Developer manuals

Appendix E - Current Technical manuals

Appendix F - Current Validation Documents

Appendix G - Current Discussions

Appendix H - Current How To Pages

Appendix I - Current Cross References