Spec styling and consistency issues

[toddbaert]

As mentioned here, there's some consistency issues with the non-normative parts of the spec. It would be great to get a thorough review of this. These proposed fixes are all editorial, not functional.

Examples of ways we can improve:

• consistent use of monospace to refer to types and glossary terms (adding more glossary terms if necessary)
• Consistent language examples: some examples are typescript others are java. I think unless the requirement specifically demands a particular language, we use choose one example language, or a consistent pseudo-code. I recommend Java because it's explicit, typed, and generally well-understood.
• consistent reference to types with spaces and in lower-case as described in the style guide (ex: flag metadata not flagMetadata)
• consistent links in non-normative text (link anything relevant)
• Consistent diagrams (I vote we use mermaid for everything). We have diagrams in the provider and hooks sections that are not mermaid.
• Consistent pluralization: now that there's multiple providers, we need to update some language which implies there's only one. This will impact normative sections, but not in a meaningful or breaking way.

cc @tcarrio

[aepfli]

I thought I could help here with the mermaid diagrams. If you think they're fine, I can add them - they also work on GitHub, so I would also suggest using them. Please let me know, if this is suitable ;) - glad to open a pull request for this.

provider

flowchart LR
    A[Application] --> |Evaluation API| B{Provider}
    B --> C[Flag managment system]

Loading

hooks

i am unsure

either a state diagram (can't change it to dotted lines, but syntactically it is the correct one)

stateDiagram-v2
    direction LR
    B : "Before" Stage
    F : Flag Evaluation
    A : "After" Stage
    E : "Finally" Stage
    X : "Error" Stage

    [*] --> B
    B --> F
    B --> X : on Error
    F --> A
    F --> X : on Error
    A --> E
    X --> E
    E --> [*]

Loading

or a flowchart (looks better, but is more a hacked version with the start point)

flowchart LR
    A("Before" Stage)
    F("Flag Evaluation")
    B("After" Stage)
    C("Finally" Stage)
    E("Error" Stage)

    Start( ) --> A
    A --> F
    F --> B
    B --> C
    A -.-> E

    F -.-> E
    E -.-> C
    C --> End( )

Loading

[Kavindu-Dodan]

state diagram

I like the state diagram as we can define the operation on the transition compared to flow chart.