The Ed-Fi “Classic Dashboards” are no longer supported through the Ed-Fi Alliance. You can still receive support and maintenance through the Ed-Fi vendor community. Please look at any of the vendors’ dashboard solutions on the Registry of Ed-Fi Badges or the Ed-Fi Starter Kits if you are looking for a visualization solution to use with the Ed-Fi ODS. This documentation will remain available to assist existing Classic Dashboard implementers.
General Writing and Usage
Itzel Torres
This section discusses general guidelines for authoring metrics documentation.
Business Rules, Bullet Lists Within. Apply bullets to inline lists of alternate rules (see MET-329 for an example). These are often a sequence of rules beginning with "If the metric value..." Don't apply bullets to a single rule, though.
Business Rules, Shared. Some business rules are defined in one place (typically a JIRA ticket) but referenced by multiple Metric Instances. Care must be taken to ensure that shared business rules are written generically, and not specific to a particular metric. For example, the definition for the Difference from Goal - District rule reads, "For district with a metric value calculated, Difference From Goal = District Goal - Metric Value" as opposed to "For a district with attendance calculated, Difference From Goal = District Goal - Metric Value." In JIRA terms, the "Issue Links" on the business rule ticket will usually show "where" a rule is used, so authors should be able to tell at a glance where a particular rule appears.
Capitalization of Real-World Terms. Avoid capitalizing real-world terms like "school" or "year" or "grading period" unless you're specifically and only talking about the entity or element name. For example:
- Metric value for each elapsed term. [OK]
- Metric value for each elapsed Term entity [also OK]
Metric value for each elapsed Term
Citations. Citations in metric documentation are brief, usually with the author(s) and year or the report title and year, enclosed in parenthesis. For example, "(Balfanz & Byrnes, 2012)." After a citation has been made, the study can be referenced inline, for example, "...as demonstrated by Balfanz & Byrnes, early intervention is essential."
Metric Descriptions, Length Of. Metric descriptions should include all relevant facets of a metric, including goals, trends, and similar. See MET-651 (in context in the Student - State Offenses documentation) for a good example.
Metric Names, Capitalization Of. When speaking generally or discussing a group of metrics, do not capitalize metric categories or names (e.g., "...when viewing attendance metrics, educators should..."). However, when discussing a specific Class or Instance, then the metric name is capitalized, usually followed by the word "metric" to make clear we're talking about something specific (e.g., "Course Grade metrics are a set of related metrics that...").
Metric Names, Grade Treatment. Some metrics are specific to a grade and have a reference to the grade in the title. Format the grade references as in "On Track to Graduate (10th Grade)". If the grade level is part of a descriptive title, then it's okay to leave it inline, as in "District - Algebra I 9th - Passing or Have Passed by 9th".
Notes. Inline notes in business rule text should be in a separate paragraph and prefixed with "Note:" (i.e., bold, followed by a colon).
Quote Literal String Values. Surround literal text/string values with double quotes (e.g., "1-Good", and "3-Bad"). You don't need to quote numbers.
Space Between Paragraphs in JIRA. Embedded JIRA content doesn't come in formatted with paragraph styles, so insert a carriage return between paragraphs to match the Confluence spacing.
Studies, Age Of. Except for a few seminal studies (e.g., A Nation at Risk), documentation writers should strongly prefer studies that are less than 15 years old. On every documentation revision, editors and business analysts should make an effort to source current research.
Title in Title Case. Metric titles (i.e., the Summary field in JIRA) should be title case throughout.