Reorganizing the Specification and Incorporating Reference Material

[kriswest]

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

Historically, only the 4 'specification' documents have been considered to be the official parts of the FDC3 standard (as defined here https://fdc3.finos.org/docs/fdc3-intro#specifications), that are voted on by FDC3 participants, with everything else considered to be supporting documentation only. However, the 'specification' documents do not provide a complete definition of FDC3.

For example, the specification for the APIs (https://fdc3.finos.org/docs/api/spec) does not include a full set of definitions for the API calls, their signatures and expected behaviour. However, this information is provided in the API reference documents (e.g. https://fdc3.finos.org/docs/api/ref/DesktopAgent) and Typescript source files (these are at least weakly referred to in the API specification).

Each section also includes an overview document, which provides a brief introduction to each part of the standard, including information that is generally repeated in more detail in the current specification documents. However, the content provides a useful introduction, which could be moved forward to the introduction section.

Hence, it is recommended that:

• The current 'specification' documents are renamed to remove 'specification' from their names, to ensure that other documents also form an official part of the standard
• The navigation of the standard website is updated to:
  • Clearly differentiate introductory or 'getting started' content from the formal parts of the 'Standard'
  • Ensure other documents are clearly part of the standard
• The 'overview' documents are moved to the 'getting started' section, which sits outside the 'Standard' documentation.
  • Duplication between the overview documents and 'Standard' documentation is expected.
• The reference documents are formally included as part of the Standard
  • Any duplication between the reference documents and 'specification' documents should be removed (particularly in the Context and Intents documents)
• Governance documentation is provided, clearly defining the formal part of the standard

Adopting these recommendations is closely related to implementation of the other recommendations in issues:

• The Big Picture: Standard and Parts #482
• Part Sections and the Use of the Word “specification”  #483
• Compliance #484

Deliverables

Navigation and Structure

Proposal(s)
Refactor the navigation structure as given below:

• Getting Started
  • Introduction <-- Introduction to the four parts of the specification + use-cases intro
  • Why FDC3?
  • FDC3 Charter
• Use-cases
  • Equity sellside trader
  • Buy side Portfolio manager
  • …
• Implementations <-- new section proposed by issue Create an **implementations** section in the FDC3 website #466
  • Platform Providers
  • Application Providers
  • Tools and Training
  • Custom Types and Intents
• FDC3 Standard <-- new heading collecting formal specification parts and supporting docs
  • Compliance <-- define terms used throughout main spec, as per Compliance #484
  • Glossary <-- New - a place to collect up definition of terms
  • References <-- New - external specs or technologies we depend on
  • Supported Platforms <-- moved from 'getting started'
  • API Part
    • Overview <-- Content from existing specification and overview documents
    • DesktopAgent <-- Content from existing reference documents
    • Channel
    • Globals
    • Types
    • Metadata
    • Errors
  • Intents Part
    • Overview
    • Start Call
    • Start Chat
    • …
  • Context Data Part
    • Overview
    • Context
    • Contact
    • …
  • App Directory Part
    • Overview <-- collect up discovery and usage information
    • Reference <-- OpenAPI spec

Content refactoring

Proposal(s)

• Overview documents to be reviewed and content re-used as part of the introduction (not an official part of the standard) and any definitions moved to the new 'Overview' documents, which will also contain content from the content of the existing specification documents
• Removal of duplication between current 'specification' documents and reference documents -> creating a new Overview document to replace specification in each part
  • Easier to read, easier to maintain
• Migrate compliance statements from the Compliance doc into the standard documentation (as per Compliance #484)