New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve the manual #3246

Closed
bbatsov opened this Issue Jun 27, 2016 · 7 comments

Comments

Projects
None yet
6 participants
@bbatsov
Collaborator

bbatsov commented Jun 27, 2016

Some of you might have noticed that our long README was recently replaced by a manual (http://rubocop.readthedocs.io/en/latest/). This was just the first step, however, as the content of the manual was simply lifted from the README and rearranged a bit. To get where I want us to be we need to:

  • improve the prose a lot (which is related to extending many of the existing sections with additional explanations and so on)
  • add some listings of all the cops (e.g. as in http://www.foodcritic.io/#FC003)
  • add sections on extending RuboCop
  • add some FAQ/troubleshooting sections

I think this is one of the most important task for the project going forward and I'd love it if you could lend me a hand with it!

@connorshea

This comment has been minimized.

Show comment
Hide comment
@connorshea

connorshea Jul 3, 2016

SCSS Lint's list of linters is a really good example to base the cop listing off of: https://github.com/brigade/scss-lint/blob/master/lib/scss_lint/linter/README.md

connorshea commented Jul 3, 2016

SCSS Lint's list of linters is a really good example to base the cop listing off of: https://github.com/brigade/scss-lint/blob/master/lib/scss_lint/linter/README.md

@smackesey

This comment has been minimized.

Show comment
Hide comment
@smackesey

smackesey Aug 3, 2016

+1 on listings of all cops. I am new to RuboCop and just read through the manual and README. I was continually frustrated by the lack of a reference for all the standard cops. Eventually I discovered I could run $rubocop --show-cops.

smackesey commented Aug 3, 2016

+1 on listings of all cops. I am new to RuboCop and just read through the manual and README. I was continually frustrated by the lack of a reference for all the standard cops. Eventually I discovered I could run $rubocop --show-cops.

@bbatsov

This comment has been minimized.

Show comment
Hide comment
@bbatsov

bbatsov Aug 4, 2016

Collaborator

PRs welcome. :-) Unfortunately I'm really short on time and won't be able to tackle this myself in the foreseeable future.

Collaborator

bbatsov commented Aug 4, 2016

PRs welcome. :-) Unfortunately I'm really short on time and won't be able to tackle this myself in the foreseeable future.

@Drenmi

This comment has been minimized.

Show comment
Hide comment
@Drenmi

Drenmi Sep 24, 2016

Collaborator

@bbatsov: Tangentially related. I have quite a bit of supporting material I created for myself to learn how to contribute to the codebase. Do we have something like a developer manual? If not, do we want one? If so, where do you think it should go? 😀

Collaborator

Drenmi commented Sep 24, 2016

@bbatsov: Tangentially related. I have quite a bit of supporting material I created for myself to learn how to contribute to the codebase. Do we have something like a developer manual? If not, do we want one? If so, where do you think it should go? 😀

@bbatsov

This comment has been minimized.

Show comment
Hide comment
@bbatsov

bbatsov Sep 24, 2016

Collaborator

Just add a new section to the existing manual.

Collaborator

bbatsov commented Sep 24, 2016

Just add a new section to the existing manual.

sihu added a commit to renuo/rubocop that referenced this issue Sep 27, 2016

@sihu

This comment has been minimized.

Show comment
Hide comment
@sihu

sihu Sep 27, 2016

Contributor

I created an index of all available cops and added the description and the URL to the StyleGuide, which you get by $rubocop --show-cops.. Now manual/cops.md is a really long file. What do you think about splitting it up:

  • cops.md:
    • overview and description of the cop-types
    • index of all cops-titles with links to detailed information
  • seperate file for each type eg. cops_style.md, cops_rails.md:
    • including description, examples for each type

Still open for the overview:

  • examples for each case
Contributor

sihu commented Sep 27, 2016

I created an index of all available cops and added the description and the URL to the StyleGuide, which you get by $rubocop --show-cops.. Now manual/cops.md is a really long file. What do you think about splitting it up:

  • cops.md:
    • overview and description of the cop-types
    • index of all cops-titles with links to detailed information
  • seperate file for each type eg. cops_style.md, cops_rails.md:
    • including description, examples for each type

Still open for the overview:

  • examples for each case
@pocke

This comment has been minimized.

Show comment
Hide comment
@pocke

pocke Sep 27, 2016

Member

Do we have something like a developer manual? If not, do we want one? If so, where do you think it should go?

I've added development.md in #3533 .
https://github.com/bbatsov/rubocop/blob/master/manual/development.md

Member

pocke commented Sep 27, 2016

Do we have something like a developer manual? If not, do we want one? If so, where do you think it should go?

I've added development.md in #3533 .
https://github.com/bbatsov/rubocop/blob/master/manual/development.md

sihu added a commit to renuo/rubocop that referenced this issue Sep 27, 2016

sihu added a commit to renuo/rubocop that referenced this issue Sep 27, 2016

sihu added a commit to renuo/rubocop that referenced this issue Sep 27, 2016

sihu added a commit to renuo/rubocop that referenced this issue Sep 27, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 15, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 15, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 15, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 15, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 15, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 15, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 16, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 17, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 17, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 17, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 17, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 17, 2016

sihu added a commit to renuo/rubocop that referenced this issue Oct 17, 2016

@bbatsov bbatsov closed this Sep 10, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment