search

alexandru / scala-best-practices

A collection of Scala best practices
4.39k stars 623 forks source link

explicit section/subsection numbers make it harder to contribute #52

Open wookietreiber opened 6 years ago

wookietreiber commented 6 years ago

The explicit section/subsection numbers make it harder to contribute.

I realized this when I wanted to make a contribution to a section, while the same section had an ongoing pull request using a new subsection number. This leaves me with two choices:

  1. Pick the same section number as the other pull request. Someone will then need to rebase, depending on which pull request gets merged sooner.
  2. Pick the next section number based on the other pull request. This assumes, that the other pull request will be accepted and I would need to base my change on that pull requests branch.

Both choices are sub-optimal.

I would like to bring the decision up for discussion to remove all explicit section numbering from all markdown sources. I think, we don't need them. Removing them has the following advantages:

  1. less fuss, easier contributions

    As explained above.

  2. no broken links

    It may happen, that a section or subsection gets removed. Then, first, you would need to change all following numbers. All saved/bookmarked/referenced hyperlinks would be broken (especially outside of the project!), because the section number and subsection number is in the hyperlink, e.g. https://github.com/alexandru/scala-best-practices/blob/master/sections/2-language-rules.md#29-must-not-use-null

  3. less visual noise

    Looking at the TOC in the README, the section numbers don't serve a real purpose. You can find your way around just as well without them. The order of the sections is important, e.g. preface before hygienic before language, etc. You don't need section numbers for that and, in my opinion, they don't add any value.

Also note, that the content this project provides can only be viewed within the confines of GitHub at the moment. I am a strong advocate of GitHub pages and similar tools that automatically convert your stuff to nice looking web pages with less visual noise. This provides a very structured way of creating full-fledged web pages to view the content without all of the visual noise of the GitHub Web UI.

As an example, take a look at a small git knowledge base I prepared for my users at work: this is the repository and this is the resulting, automatically created, GitHub page. The GitHub page looks a lot nicer, doesn't it? It also has way less visual noise so it is less distracting and thus easier to read and learn.

As a teaser: I think, it is even possible that GitHub pages and friends have stuff that allow you to create multilingual pages within a single repository more easily. I don't know for sure, though, as I have not yet done that myself.

alexandru commented 6 years ago

You might be right, having those numbers is pretty tedious.

Would you be willing to do a PR?

wookietreiber commented 6 years ago

Maybe I'll find some time tonight.