Schematics summarising rules/processes for Conventions changes

[sadielbartholomew]

The pages on 'Rules for CF Conventions Changes' and on 'Rules for Correcting Errors in CF Documents' are very clear and useful, but necessarily quite wordy. I propose that we create some schematic(s), probably in the form of multiple flow charts, which can sit with the text to summarise chunks of the information there, for example:

• processes involved;
• parties involved and their roles (proposer, moderator, etc.);
• links between steps, especially those where there may be a wait involved;
• and so on...

It may be that some diagrams along these lines exist already? If so, we can use those as a starting point, but I think anything added must be:

• up-to-date (naturally), especially not with any contradictions to the text;
• able to be generated and edited with some form of source code, to allow to easy re-creation, tweaking and diffing, when changes are required. I suggest we could use a tool such as mermaid which allows this via a fairly simple syntax and has a live editor which is great to create something quickly.

As a side note, I am proposing this as something that might be good to tackle for the 2022 CF Meeting Hackathon (I will add a summary to cf-convention/discuss#152) because it is something that could be done quite quickly and would be educational (regarding the processes) as well.

[erget]

I think this is a good idea - and I can prove it, since I have a very old PR (#171) that tried to implement this. It auto-built an activity diagram from a PlantUML spec.

I think that PR could essentially could be re-used if we revive #102 where it was discussed. At a minimum we could leave the rules as they are and use the diagramming and auto-build features. What do you think?

[sadielbartholomew]

Thanks @erget, that sounds brilliant to me, and in particular the diagram you already had, as linked to in your comment, looks really useful and is exactly the kind of thing I had in mind (but better even)! So maybe this issue becomes simplified into a case of, say:

• summarising #102 between ourselves to capture the context;
• reviewing that diagram to check it is up-to-date and tidying it so it is as clear as it can be;
• thinking about whether there is any other information that hasn't been captured there that could be added or incorporated into one or more new diagrams.

In that case, I think just one hour or so could suffice to get all of that completed. Possibly a bit optimistic, but it does sound like you have already done most of the hard work!

[erget]

Cool! Maybe we can finish it up in Santander then :)

[JonathanGregory]

Please see https://github.com/cf-convention/cf-conventions/issues/369, which may lead to some changes in the process to be represented by the schematic.