Spec-Spec Updates

[rigelrozanski]

Here are some suggestions to discuss for the spec-spec

• add section discussing avoiding the use of pseudo code
• overview.md -> README.md as per Add readme to all specs #3587
• consider adding numbers to the beginning of each file names (aka. 01_overview.md, 02_state.md, etc. ) to facilitate ease of ordering if somebody was to print the documents, the nice thing about the LaTex F1 spec is that the entire spec flows as one document, we should allow our specs even though they are split up into separate documents to have this same flow
• Add appendix.md - would be good as a "rip off" page to describe equations etc. which are written all throughout the docs
• Add state_transitions.md with descriptions, I think this will and should be a standard section for a decent number of modules

CC @jackzampolin @ValarDragon @sunnya97 @cwgoes @alexanderbez

[ValarDragon]

State_transitions.md sounds like it would be amazing. Its takes off so much mental burden to just be able to refer back to a diagram / table or two to then frame discussions / improvements around. One example of a table and diagram pair that I refer back to / use a lot is section 10 of the Aurora paper.

I definitely agree that a linear flow through the docs would be great. I definitely had trouble parsing through some of our existing specs due to it being in an unknown order to me. That could be done either via filenames, or perhaps via overview providing links to other sections in the correct order, with each section linking to the following section and previous section as well?

[rigelrozanski]

I mean we could have the flow in overview.md as well, but I think we def want it in the filenames for organizational purposes - I almost would prefer it to not be in the overview because it's less to maintain and obvious, but I don't feel that strongly about it