Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Part Sections and the Use of the Word “specification” #483

Closed
RexJaeschke opened this issue Oct 25, 2021 · 0 comments · Fixed by #712
Closed

Part Sections and the Use of the Word “specification” #483

RexJaeschke opened this issue Oct 25, 2021 · 0 comments · Fixed by #712

Comments

@RexJaeschke
Copy link
Contributor

RexJaeschke commented Oct 25, 2021

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

The terms standard and specification are often used interchangeably in the IT industry. As we’ll have a single Standard, we need to be careful how we use specification (with leading lowercase letter).

Using the API Part as an example, three of the Parts have the following layout:

  • API Part
    • API Overview
    • API Specification
    • Reference

in which I’ll call these sublevels “sections.”

Although the App Directory Part uses slightly different section names, it does have “API Directory Specification,” and it’s this use of “Specification” by all Parts that needs to be addressed.

As best as I can determine, both the Specification and Reference sections can/do contain requirements, but I don’t yet understand why the Reference is split off from the Specification.

Proposals:

  1. There probably should not be any occurrences of “Specification” (spelled with an uppercase S); instead, consider “Standard” or “Part.”
  2. Find all occurrences of “specification" (lowercase) and see if they can/should be changed to something else.
  3. Someone to write a one-sentence description of the intent of the Specification and Reference sections, so we can see how they might be retained as is, combined or reorganized, and with what titles.
  4. Make Part section names consistent. For example, “API Overview” has “Usage” with numbered examples, while “Intents Overview” has “Using Intents” with unnumbered examples. “Getting Started, Support Platforms” has “Usage.”
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants