Description
The basic description of the new service goes here. If you have a more extended description, you may want to select a portion of it (rather than the whole thing) as the excerpt that is shown on the main page. Just place the "excerpt" macros around the part you want to show up on the description page.
There will often be one main entity service, and then a set of relation services. The relation services are generally grouped with the main entity, and should be described there. E.g., for a Person service, a Person-to-Person relationship mapping would also be described. Where to put things will be a judgment call. E.g., for Contact info, the Person-Contact relation and the Organization-Contact relation services probably belong with the Contact service, but should perhaps be mentioned in Person and Organization, respectively.
Assumptions
- Try to be explicit and exhaustive, but not pedantic.
- Patrick Schmitz (Unlicensed): If there is an active discussion or comment, you may want to call it out as a sub-bullet. This example also uses a color macro to call it out, and provides a link to a given user to indicate that this is a particular contributor's position.
Subtopic
- More assumptions around peripheral subject
- Ex. An example of the case
- Yet another assumption
- Details of the assumption
- Nitty-gritty detail 1
- Nitty-gritty detail 2
- Details of the assumption
Key Concepts
- Especially things that become common sense, and so usually missed by new reviewers
Dependencies
- Note other services that are consumed or that are closely related to this one
Background Documentation
- If we have notes from community design meetings, link to them here.
- If we have relevant sections in Spectrum or another such document, link to them here (or cite section numbers, etc.)