christopheradams / christopheradams/elixir_style_guide

Rationale for choices

Open
#117 8 comments 1 reaction 0 assignees View on GitHub
discussion question
Dominant language
Elixir
Stars
4.4k
Forks
300
PR merge metrics
No merged PRs in 30d

Description

One of the things I discussed with Christoper earlier via Slack is that I didn't agree with some of the positions taken in the style guide. That's not a criticism of the guide; in fact, I think that the chain of maintainers for this guide has gone to great lengths to ensure that the guide is community driven.

However, I think that the guide can be improved by presenting the rationale of why the guide adopts each particular choice it does. That way, when someone expresses disagreement, they can present a counter-argument to the current choice that can be evaluated by the community. That will make future discussions like #116 easier since the evaluation happens without having to dive through "why was this decision made in the first place; what was the rationale?"

Swinging to the opposite side, I think it would be good to have a note at the top stating that we are presenting a community-reviewed set of options that allow for cohesion and a starting point. I realize that's partially addressed in the "Getting Involved" section, but I just think it would be good for people to see it when they first start reading the guide. We're not intending to create solemn law that must not be violated upon pain of exile. Or as I was telling @christopheradams, this ["is more what you call guidelines than actual rules."](https://www.youtube.com/watch?v=6GMkuPiIZ2k)

Contributor guide

Open the contributing guide

Research direction

Review the style guide sections discussed in the issue and the existing “Getting Involved” section, then compare the unresolved rationale questions with issue #116. Done means the guide explains why its choices were made and clearly states near the top that they are community-reviewed guidelines rather than absolute rules.

Written by the indexing model from the issue text.

Assessment

Tech stack
elixir
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.