Skip to end of metadata
Go to start of metadata
Icon

this document is under review and portions are out of date

Purpose

This document describes Kuali Rice's documentation policy by detailing out the expected documentation on a per feature basis. It also describes where to put the documentation.

Documentation Toolset

  1. DocBook - Release Documentation for Rice 2.0 and beyond is built with DocBook.
  2. Wiki - Work under development, collaboration documentation, and older documentation is in the wiki.
  3. Google Docs - Most meeting notes and any document on work under development that requires more formatting than the wiki (i.e. spreadsheets, formatted documents, presentations) is stored in Google Docs.
  4. Doc2Help - Release documentation for Rice 1.x versions was built with Doc2Help.

Types of Functional Documentation

  1. Installation Guide Documentation - This explains how to install Rice.
  2. User Guide Documentation - This explains the functional purpose of a feature and how end-users would expect to interact with the feature.
  3. Technical Guide Documentation - This explains how a core feature is designed and built. This is of importance to core contributing developers and others who may want to extend a feature.
  4. Developer Guide Documentation - This explains how a core feature can be used by an application developer who is looking to use Rice for building software.

Installation Guide Documentation Expectations

Content
  1. Verbosely explained data and settings detailed out as much as possible should appear here
  2. Visual aids and screen shots should also appear here
Location
  1. Any documentation related to installation or configuration of Kuali Rice should go under the expanded trees shown below.
  2. General documentation for installation should go under the "Installation Guide" tree. Specifics about how to actually install it should go under "Installation and Configuration".
  3. Module specific documentation should go under the appropriate "<SPACEKEY> Module Configuration" page.

User Guide Documentation Expectations

Content
  1. A description of the feature and how it would be used by an end-user of a system
  2. Screenshots of the feature
  3. Eventually, a link to the demo system and information about how one can try out the feature
Location
  1. Any documentation related to using the end product software produced by Kuali Rice and its frameworks or services, should go under the expanded trees shown below.
  2. General documentation for using Rice should go under the "User Guide" tree.
  3. Module specific documentation should go under the appropriate "<SPACEKEY> User Guide" page.

Client Developer Guide Documentation Expectations

Content
  1. Examples of when a developer would leverage a feature in development terms, referencing the user guide documentation as well
  2. Step-by-step instructions showing a client developer how to configure their system to be able to use the feature
    • Including screenshots and code snippets
  3. Step-by-step instructions showing a client developer how to implement the feature in their code
    • Including screenshots and code snippets
  4. References to the Sample Application where a feature is actually implemented
Location
  1. Any documentation related to building software using Kuali Rice and its frameworks or services as a programmer, should go under the expanded trees shown below.
  2. General documentation for using developing applications using Rice should go under the "Client Developer Guide" tree.
  3. Module specific documentation should go under the appropriate "<SPACEKEY> Client Developer Guide" page.

Technical Guide Documentation Expectations

Content
  1. Conceptual/architectural diagram showing how the core feature was built - with explanation
    • Includes illustrating how this feature interacts or relates to other features
  2. Class diagram showing how the core feature was built - with explanation
  3. Database diagram (ER) showing how the DB was designed - with explanation
  4. A text based description of why the feature was designed the way it was
  5. Explanation of how one would extend the feature
  6. References to the Sample Application where a feature is actually implemented
Location
  1. Any documentation related to how Kuali Rice and its frameworks, services, etc were built, should go under the expanded trees shown below.
  2. General documentation for using developing applications using Rice should go under the "Technical Developer Guide" tree.
  3. Module specific documentation should go under the appropriate "<SPACEKEY> Technical Developer Guide" page.

Other Documentation

Rice Contribution Policies

Content
  1. Detailed documentation about policies and procedures that developers must follow when contributing code or documentation to Kuali Rice
  2. Pictures
  3. Explicit instructions
Location
  1. Any documentation about policies and procedures that developers must follow when contributing code or documentation to Kuali Rice should go under Rice Contribution Policies.

Development Team Home (Team Docs - Meetings, Project Plans, Status Reports, Retreat Notes, etc)

Location
  1. Any documentation about internal to the Rice team or any documentation that's important to have for the team to operate that shouldn't be public, should go in Google Docs.

Enhancement Proposals

Location
  1. All requested enhancements to Rice should be added to the Kuali Rice Roadmap Jira Queue. They will the be prioritized by the ARC during the regular voting process.
  2. Any documentation related to enhancement proposals should go under Enhancement Proposals.

Anything Else

If you aren't sure where certain types of documentation should go since you don't think it fits into any of the categories above, please email rice.collab@kuali.org with your question.

Expectations of Contributing Developers

Contributing developers regardless of work type (bug, enhancement, etc), are expected to share some responsibility in documenting any new features or changes that are made, in a consistent fashion laid out by the documentation policies above.

In most cases, the contributing developer will be responsible for a basic first cut at all four types of feature based documentation, using format detailed in the Enhancement Policy.

  • No labels