Documentation Not Helpful

[mslinn]

The official documentation for Thor at http://whatisthor.com/ consists of one short web page, and is woefully incomplete. For example, it makes no mention of templates. This tiny, single-page website provides very little value.

The wiki at https://github.com/rails/thor/wiki/Method-Options says: .

NOTE: a good part of the documentation here is outdated, see the website instead: http://whatisthor.com/

However, http://whatisthor.com/ also makes no mention of method_options either.

Thor is well-designed, well-written, and well-maintained. Its documentation, however, presents a significant barrier to those who are keen to learn it (like me).

You might as well save the expense of the yearly registration fee for http://whatisthor.com/, and just maintain the documentation on GitHub instead.

I am writing about my experience with Thor on my site: Ruby Gem Scaffold Generation With Thor. The article will be updated as I complete the generator program. The article has a section that discusses Thor's documentation. This is the generator, based on Thor.

[rafaelfranca]

Agree. Mind to take the opportunity that you are writing about your experiences and move the documentation in the website to the README of the project and remove all mentions to http://whatisthor.com/?

[mslinn]

I would be willing to do what I can with the README.

As my article states, I am unclear what the thor command does; I do not believe what I wrote is correct. It does not show any of my thor subclasses, so the explanation probably has unstated assumptions. If someone provides me with a sentence or two about the high-level purpose and motivation of the thor command, I will submit a PR for the README, and I will correct my article.

Other pages refer to http://whatisthor.com, and those need to be removed as well. At least one such page states that it is itself inaccurate and should be disregarded (for example, https://github.com/rails/thor/wiki/Method-Options). This page is no worse than any other source of documentation for this project, so the disclaimer should be removed along with all references to http://whatisthor.com.

Incidentally, I invite remarks about my article to be sent to mslinn@mslinn.com, so I may improve it.

[mattbrictson]

If someone provides me with a sentence or two about the high-level purpose and motivation of the thor command

Does this sound accurate?

Thor is a gem for building CLIs in Ruby. It serves multiple use-cases:

1. The Thor gem adds a thor command to your shell. Much like Rake, you can define command-line scripts in Ruby, place them in a Thorfile, and then execute them using thor. Compared to Rake, Thor offers a richer, modern set of CLI features and a more intuitive programming model.
2. Thor also provides tools for building entire packaged CLIs. For example, the CLIs of mrsk, bundler-audit, and good_job are all built using Thor.
3. Thor contains a powerful library of methods for generating files and directory trees from Ruby and ERB templates, as well as conveniences for prompting for user input and printing output on the console. These methods can be used within Thor CLIs or from your own Ruby code.
4. Finally, Thor is the foundation of the Generator and App Template system in Rails. Commands like rails new and rails generate devise:install use Thor's library of template methods behind the scenes.

[mattbrictson]

Maybe a more concise way of saying it is:

Thor is a task-runner, a framework for building CLIs, and a library of template and generator methods.

[mslinn]

I like it, thanks!

Proper documentation would reorder those, such that the briefest summary was presented first, then a longer exposition, then as much additional detail as was appropriate.