A proposal for guideline pages

[vburzynski]

A proposal for structuring sub-pages that provide additional details to guidelines.

Example:

• a link in the ruby README.md file:

  guides/ruby/README.md

  Line 5 in d7bd2d1

  - [Use an opinionated set of rules for Rubocop](./Use an opinionated set of rules for Rubocop.md)

• a page explaining the guideline:

  guides/ruby/Use an opinionated set of rules for Rubocop.md

  Line 1 in d7bd2d1

  # Use an opinionated set of rules for Rubocop

[MatheusRich]

If we accept these meta-guidelines, we should use a linter of sorts to enforce them (at least the ones we can)

[vburzynski]

That would be a useful tool to have 👍
I could see the headings being an easy one to enforce.

[MatheusRich]

Once we have one, a real example would be good

[vburzynski]

here's a WIP example - main...vb-modifying-nme-standard

[MatheusRich]

Should all guidelines have a page?

[vburzynski]

🤔 That's a great question...

• initially I think it'd be unreasonable to enforce this for all existing guidelines. I wouldn't want to rapidly generate a bunch of pages. If we went that direction, I think it should be thoughtful and deliberate.
• I do think that there are a lot of existing guidelines that could benefit from a revisit and adding a guideline page to flesh out our thoughts on why it's useful and important to follow.
• Having reasoning behind every guideline, even ones that appear obvious, can make them more approachable to everyone and to every level of experience. The work that goes into articulating the reasoning behind a guideline can facilitate analysis of assumptions; avoid miscommunication or confusion; clarify one's thinking; and reveal gaps in our own understanding.
• I could see enforcing this for new guidelines. It can encourage discussion and preserve more context for the next time someone reviews a guideline to see if it's still as relevant and applicable as it once was.

[MatheusRich]

At first glance, this seems too rigid to apply to all pages. I'd love for us to experiment with just having guideline pages at all before defining such a strict format. That said, it might be good to have some form of template to help shape ideas/thoughts.

[vburzynski]

I've imagined this being more of a starting point to underscore the angles from which we might examine a guideline and to identify the components which could be put into an articulated reasoning. This is more to encourage a bit of internal consistency of approach. The emphasis is not on following a specific structure.

• There's virtue to irregularity. I'd like to encourage common components, but highly encourage creativity and flexibility in how that is composed and presented.
  • https://www.eastgate.com/garden/Virtue_of_Irregularity.html
• at the same time, repetition is a valuable cue
  • https://www.eastgate.com/garden/Repetition.html
• So an effective strategy is the artful combination of irregularity with some order to signal intent. Building more of a garden that composes structural elements with surprise and experimentation. Avoiding the sterility and rigidity of farmland while also avoiding untamed wilderness.
  • https://www.eastgate.com/garden/Gardens.html

Also things that are entirely unsurprising yield no information (surprisal being a measure for the amount of information exchanged in a communication between two entities).

So yes, I would love to explore more formats