The Big Picture: Standard and Parts

[RexJaeschke]

Formalizing the FDC3 Standard documentation

This issue has been raised as part of work, sponsored by FINOS, to improve and formalize the documentation of the FDC3 standard.

Issue description

After reviewing the spec, my thinking w.r.t the top-level organization is to have one Standard made up of the following Parts (note the leading uppercase letters):

• Getting Started
• API Part
• Intents Part
• Context Data Part
• App Directory Part
• Use Cases

A Part may contain informative text only, normative (requirements, that is) text only, or a combination of both.

Note: There has been private discussion about splitting “Getting Started” into two Parts, one being informative and providing an overview of the other Parts, the other being normative and introducing compliance along with some other things (such as core terms and definitions, and references to required specs [such as ES6, TypeScript, and RFC 2119]).

Proposals:

1. Find all occurrences of “specification” that should be “Standard” and change them.
2. Within the Standard, use “this Standard” rather than “the FDC3 Standard.” Wherever possible, omit “FDC3” as a qualifier, as everything in the Standard is about FDC3 unless otherwise specified. "FDC3" may still occasionally be used as a qualifier in any cases where disambiguation is required.
3. Find all occurrences of “specification” that should be “Part” and change them. Mark all Parts as Parts (including “Getting Started” and “Use Cases.”)
4. Assuming that compliance to the Standard requires compliance to all of the Parts, at any time, that set of Parts will be “synchronized.” As such, remove the “1.2” suffix from each Specification heading within Parts and add that suffix to the title of the whole Standard.