CCSMB / Standards

Standard file formats, APIs, network protocols, and more for ComputerCraft
Other
8 stars 7 forks source link

Miscellaneous issues with existing "standards" #32

Open hugeblank opened 3 months ago

hugeblank commented 3 months ago

This is my first time coming across this project. In my opinion the concept of having standards for CC like this is comedic on its own, but I was at least hoping I'd see some decent organization and a more impressive arrangement of standards since the last time oeed contributed to them. I was disappointed. Below is the list of inconsistencies I found in the standards:

CCSMB 1

The header defined by the standard is:

*Author: Your Name <@yourgithub>*
*Version: v1.0.0
*Last updated: YYYY-MM-DD*

The header for CCSMB 1 itself does not follow this standard, opting to add an extra newline and a description, not defined by the standard:

*Author: Tomodachi94 <@tomodachi94>*

*Version: v1.0.0*

*Last updated: 2022-11-07*

This RFC defines the protocol for defining and submitting a standard to the CCSMB.

Later in the file:

The RFC should be written in a professional tone. Readers are expected to have a basic understanding of programming jargon and Lua programming.

bit of a nitpick but I feel like the term "programming jargon" coming right after "professional tone" completely side-steps the goal of the section. It could be written better.

CCSMB 2

CCSMB 6

CCSMB 7

CCSMB 10

tomodachi94 commented 3 months ago

Thank you for all of this actionable feedback! I'll do my best to address and provide solutions for the issues you raised.

Header formats

The newlines being added was due to the Markdown renderer only making a visible linebreak when two consecutive linebreaks are added. CCSMB-1 should be adjusted to account for this.

Additionally, we should consider adding markdownlint to this repository to enforce consistency.

CCSMB-1

CCSMB-1 is not as thorough as it should be. It has numerous shortcomings, and was mostly written by myself before I had much experience with writing standards.[^1]

CCSMB-10 and the review process

In my opinion, CCSMB-10 didn't go through a thorough-enough review. We should adjust our policies to ensure that specific expectations are set for a review.

[^1]: There was actually a discussion yesterday about this in the CCSMB Discord.