Contributing: Improve examples guidance

[jpmckinney]

From https://docs.google.com/document/d/1Tl_0vv1QTt1UzJ2WGie5gOFyG6CTzILtSkiChglJ0BQ/edit

---

Adjusting examples to follow a standardized format and to focus on learning objectives would add clarity and practicality to OCDS documentation.

Process note - This guidance is useful for contributors and important enough to be its own page in the development handbook.

• Consider - Adding a section to the development handbook on examples that provides much more detail and guidance on when to use examples, what they usually contain, and their process for creation and styling.
• Consider - Applying uniform styling to examples that includes use of admonition and no link in the navigation bar.

Purpose - Examples are currently inconsistent in their length, detail, and elements leading them to be less useful than they could be.

• Consider - Organizing all examples based on a standard structure, containing objectives, guidance, ++ background, narrative++, and examples in use.

Example threads - Currently examples range from specific to certain places to very general applications and uses.

• Consider - Focusing on 2-3 main examples that can be used as a familiar narrative “thread” throughout OCDS and build on one another.
• Consider - Linking to uses of OCDS in the “wild” to show users how their application may end up looking in the long run.

Recommended new structure for examples

Each example should follow a consistent order and set of rules to help the users understand the “who, what, where, when, why, and how” of the example. Each example should contain the following components:

• Objectives (no more than 2)
• Background (link to any previous examples)
• Narrative
  • Explain concept
  • How it relates to a field in OCDS
• Code snippets
• Conclusion sentence

Clearly stating an objective will help focus the user on the “why” and should also help contributors hone in on key concepts when writing. In addition, objectives should also use verbs from Bloom’s Taxonomy to help the contributors hit the right level of understanding for users as they read through a variety of examples. Bloom’s Taxonomy is a pedagogical learning model designed to help target appropriate tasks that demonstrate learning.

With the objective stating the “why,” the background information and narrative should provide the who, what, where, and when of the example. This will help ground the user and provide a ramp to the “how” which are the code snippets for each example.