Remove the need to indent code blocks (sample)

[swiftal64]

Summary

Pros:

• We no longer have to indent code blocks.

Cons:

• We no longer have bold and non-bold sections in rule titles.

Alternatives considered:

• Instead of using a heading on the rules, use just standard bold. This causes the "details" link to hug the next rule and doesn't provide the spacing we'd like.

Reasoning

Reviewers

cc @airbnb/swift-styleguide-maintainers

Please react with 👍/👎 if you agree or disagree with this proposal.

[dfed]

I'm not sure I understand what's going on here: what problem are we solving? Can we get a little more context?

[bachand]

Here is what the visual diff looks like:

[fdiaz]

I feel like contributing is a bit harder (since you have to indent 2 spaces your code blocks), but we get better legibility by keeping the current style.

I feel like the con of not having bold/non-bold sections is a fairly big disadvantage compared to what we gain. I think we're trading the ease of reading the guide for multiple people by focusing on making life a bit easier to a couple of contributors.

Should we move this to an issue to discuss since this PR is not merge-ready based on our contributing guidelines and if we agree on doing this, then we can make a PR that moves the style guide in that direction?

[bachand]

@fdiaz can you clarify what you mean by:

I feel like the con of not having bold/non-bold sections is a fairly big disadvantage compared to what we gain

We still have bold with this new approach since we’re using a header style instead of explicit bold, right?

Also happy to discuss further in an issue.

[fdiaz]

We still have bold with this new approach since we’re using a header style instead of explicit bold, right?

Correct. But we only have bold. We can't have non-bold parts of the title so it all "looks" like the same weight when in reality IMO there are more relevant parts of the rule and less relevant. For example, the sentence of the rule should IMO be more important and highlighted than the SwiftLint part. Same with the link at the beginning. Making everything equal looses the focus on the rule itself IMHO.

[bachand]

@fdiaz, got it. Makes sense. Thanks for clarifying.

[bachand]

I like not indenting but I agree it would be nice to use bold sparingly.

[thedrick]

I agree with the points that Francisco has made here and I personally prefer the current style compared to the proposal.

[fdiaz]

Resolution

Status: Declined ⛔️

Reasoning:

This proposal made it easier to contribute to our Style Guide but (arguably) would have made it harder to read given that the rule would have been all in bold.