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.
Purpose - Examples are currently inconsistent in their length, detail, and elements leading them to be less useful than they could be.
Example threads - Currently examples range from specific to certain places to very general applications and uses.
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.
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.
Purpose - Examples are currently inconsistent in their length, detail, and elements leading them to be less useful than they could be.
guidance, ++ background, narrative++, and examples in use.Example threads - Currently examples range from specific to certain places to very general applications and uses.
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:
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.