A simple introduction. It would be good if the reader ended the introduction knowing what the spec does, even a simple key example (even detailed copy-n-paste sample a developer would use). I decent example is the LD Patch intro section.
Terminology is based on OSLC Core Overview [[OSLCCore3]], W3C Linked Data Platform [[LDP]], W3C's Architecture of the World Wide Web [[WEBARCH]], Hyper-text Transfer Protocol [[HTTP11]].
TODO: needed for public review version of standards-track specifications, more details in TC Handbook. Some examples: LDP, UBL
Call out some key problems, use cases, scenarios that have motivated this specification. References are good, especially to some Use Case and Requirements.
Optional section, though could be useful if intro can't cover it and you have enough concepts that it is worth elaborating on. A reasonable example is the JSON-LD Syntax spec.
The title of this section is flexible. Since the title of this spec should match what it does, it may not make sense to repeat it here. This section is intended to capture the conformance clauses (ie, the 'meat' of the spec).
Give your section title/id something meaningful and simple, don't include the actual section number.
Writing conformance clauses/statements: Create individual sections for each conformance clause. Each clause should cleanly map to a test case, see [[LDP]] spec and LDP testsuite for an example of this model.
For every resource that is defined, define a shape for it. There may need to be a shape for certain scenarios. Shapes are intended to be published as separate files and consumed by other applications. Shapes must be an external Turtle file (.ttl) and included. We hope to have some code that will convert it into an HTML table, or other visually pleasing forms as needed.
Like first shape, included in same file and reuses property definitions. Use hash '#' to indicate which shape this is.
This section details how OSLC clients can discover this capability. It should follow the model set by [[LDP]] and [[OSLCCore3]]. Depending on the capability, it could be defined using existing HTTP headers, HTTP OPTIONS response, content in responses such as a predicate that links a ldp:Container to some other kinds of resource (such as type URL or shape), and so on.
Each specification may define new vocabulary terms. These should be defined with consideration for global use (not within a specific type of resource). Other domains and resource types will be encouraged to reuse these.
Call all key contributors, reviewers or general groups as needed.
Many thanks to Tim Berners-Lee for inventing the Web.
The change history is up to the editors to insert a brief summary of changes, ordered by most recent changes first and with heading from which public draft it has been changed from.