You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
There probably should not be any occurrences of “Specification” (spelled with an uppercase S); instead, consider “Standard” or “Part.”
Find all occurrences of “specification" (lowercase) and see if they can/should be changed to something else.
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.
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.”
The text was updated successfully, but these errors were encountered:
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:
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:
The text was updated successfully, but these errors were encountered: