Use mermaid for flow diagrams

[burgerga]

@rbramley @mabablue

See the example contributing workflow I made in mermaid here.

You can even add click actions to the node; try clicking on the G1A node.

It's also supported in Github Markdown, except the node clicks are not supported, instead you can include the link in the node text (see G1A, you might need to zoom in to be able to click it). Mermaid should also be supported in Quarto :)

%%{init: {'theme':'neutral'}}%%
flowchart LR
subgraph actions[" "]
    direction LR
    F1A[F1 A choose issue]  --> F1B[F1 B check duplicates]
    F1B --> F1C[F1 C do quality check]
    F1C--> F1D[F1 D propose actions]
    F3{F3 perform actions}
    F3 -- rejects --> F3C[F3 C retract/disapprove it]
    F3 -- improvement required--> F3B[F3 B improve it]
    F3 -- approve as is--> F3A[F3 A qualify FSR nanopub]
    F3B --> F3A
    F1D -- hand over for review -->F2{F2 reviewer decision} 
    F2 -- rejects proposal --> F3D[F3 D assign a second reviewer]
    F3D --> F2
    F2 -- requests changes --> F1D
    F2 -- approves proposal --> F3

end
subgraph github[Github steps]
    direction LR
    G1A[<a href='https://github.com/gofair-foundation/fsr_qualification/blob/main/CONTRIBUTING.md#g1-a-setup-steps'>G1 A</a> Set-up] --> G1B[G1 B document quality check]
    G1B --> G2A[G2 A document review]
    G2A --> G1C[G1 C document qualification]
end
G1A --> F1A
F1B --> G1B
F1C --> G1B
F1D --> G1B
F2 --> G2A
F3 --> G1C

classDef editorActions fill:#eac735
classDef reviewerActions fill:#f9f35a
classDef keepNP fill:#a6cf5b
classDef removeNP fill:#d69786

class F1A,F1B,F1C,F1D,F3,F3D editorActions;
class F2 reviewerActions;
class F3A,F3B keepNP;
class F3C removeNP;
style F3C stroke:#cf4e2c,stroke-width:4px;
style F3A stroke:#63a58a,stroke-width:4px;
style G1A stroke:#d47a63,stroke-width:4px;

Top to bottom layout might be nicer (more readable, and is as simple as changing LR (left-right) to TB (top-bottom)):

%%{init: {'theme':'neutral'}}%%
flowchart TB
subgraph actions[" "]
    direction LR
    F1A[F1 A choose issue]  --> F1B[F1 B check duplicates]
    F1B --> F1C[F1 C do quality check]
    F1C--> F1D[F1 D propose actions]
    F3{F3 perform actions}
    F3 -- rejects --> F3C[F3 C retract/disapprove it]
    F3 -- improvement required--> F3B[F3 B improve it]
    F3 -- approve as is--> F3A[F3 A qualify FSR nanopub]
    F3B --> F3A
    F1D -- hand over for review -->F2{F2 reviewer decision} 
    F2 -- rejects proposal --> F3D[F3 D assign a second reviewer]
    F3D --> F2
    F2 -- requests changes --> F1D
    F2 -- approves proposal --> F3

end
subgraph github[Github steps]
    direction LR
    G1A[<a href='https://github.com/gofair-foundation/fsr_qualification/blob/main/CONTRIBUTING.md#g1-a-setup-steps'>G1 A</a> Set-up] --> G1B[G1 B document quality check]
    G1B --> G2A[G2 A document review]
    G2A --> G1C[G1 C document qualification]
end
G1A --> F1A
F1B --> G1B
F1C --> G1B
F1D --> G1B
F2 --> G2A
F3 --> G1C

classDef editorActions fill:#eac735
classDef reviewerActions fill:#f9f35a
classDef keepNP fill:#a6cf5b
classDef removeNP fill:#d69786

class F1A,F1B,F1C,F1D,F3,F3D editorActions;
class F2 reviewerActions;
class F3A,F3B keepNP;
class F3C removeNP;
style F3C stroke:#cf4e2c,stroke-width:4px;
style F3A stroke:#63a58a,stroke-width:4px;
style G1A stroke:#d47a63,stroke-width:4px;

[burgerga]

An alternative is svg (e.g., with Inkscape), since these are also editable (and can also display links I believe). Then you would have more control over the layout.

[burgerga]

And since we're talking documentation, using callout blocks could also be useful to emphasize some points: https://github.com/orgs/community/discussions/16925