Refine IMS Documentation Formatting

[timothyfcook]

The update to the criteria object and the surrounding documentation is a bit obscure.

Suggest refinements to:

• clarify the "pick one" nature of using either the IRI or the narrative properties. can you use both?
• clarify how to use the narrative property to support your actual criteria values, esp. how to use the markdown format (provide an example of .md)

[ottonomy]

Yes, both id and narrative may be used in this class. At least one is required. Displayers will presumably be able to render some Markdown into HTML along with other badge metadata and and a link if there is one.

Examples of criteria with and without narratives are provided on the examples page linked from the Criteria class http://openbadgespec.org/examples/#Criteria

[timothyfcook]

Ok, part of the issue was that certain people (me) didn't see the "Example" link next to the Object Headers. Some considerations:

• Add a "Required?" column to each of the object definitions
• More clearly explain the value of the rendered markdown
• Consider overall improvement to page formatting to make the Examples links separate from the headers
• Consider adding the Examples page to the site tree or top navigation for the documentation.

[jbohrer]

Agree with improving readability of Required? attribute. This is related to #107

[ottonomy]

@timothyfcook and @jbohrer: In this case, the intent of the existing draft is that issuers use Either a URI for criteria, a narrative embedded in the badge or both. That means that neither id nor narrative is a required property. As you develop a required column in the tables, make sure we don't neglect how this situation will be described.

In text,

BadgeClasses MUST contain either a criteria id, a criteria narrative, or both.

The existing documentation in the core document does not forcefully state this point. The current text reads:

Embedding criteria allows either enhancement of an external criteria page or increased portability and ease of use by allowing issuers to skip hosting the formerly-required external criteria page altogether.

[timothyfcook]

Going to update this to become a more general-purpose ticket to improve a few aspects of the overall documentation formatting:

Acceptance Criteria

1. Add a "Required?" column to each of the object definitions
2. Make Examples links separate from the headers
3. Add the "Examples" page to the site tree/top navigation for the main documentation page

[timothyfcook]

PR should be done against the IMS 2.0 branch