Software Engineering, Project Management, and Effectiveness
This is the emerging schema and test-cases we're using for code examples:
Code Example Schema (Template)
Code Example Schema (Template explained and test cases)
TitleInsert title that resonates from a findability perspective.
Summary Insert 1-2 lines max description of the intent.
Applies To Insert the key technologies/platform the code applies to.
Objectives Insert bulleted list of task-based outcomes for the code.
Solution Example Insert code example as a blob within a function. The blob allows quick reading of the code. It also allows quickly testing from a function, inlining within other code, or refactoring for a given context. The alternative is to factor up front, but this increases complexity and can negatively impact consumption. This leaves refactoring to the developer for their given scenario.
Problem Example List examples of common mistakes along with issues.
Test Case Insert relevant setup information. Write the code to call the functional blob from Solution Example.
Expected Results Insert what you expect to see when running the test case.
Scenarios Insert bulleted list of key usage scenarios.
More Information Optional. Insert more information as necessary. This could be background information or interesting additional details.
Additional Resources Optional. Insert bulleted list of descriptive links to resources that have direct value or relevancy.
We're using this schema for our Security Code Examples Project.