Build Awesome Command-Line Applications in Ruby 2

Writing Good Help Text and Documentation

That your app has any help text at all is great and puts it, sadly, ahead of many apps in terms of ease of use and user friendliness. We don’t want to be merely great; we want to be awesome, so it’s important that our help text and documentation be clear, concise, accurate, and useful. We’re not going to get into the theory of written communication, but there are a few rules of thumb, as well as some formatting conventions, that will help elevate our help text and documentation.

In general, your in-app help documentation should serve as a concise reference. The only portion of the in-app help that needs to be instructive to a newcomer is the “banner,” that is, the one-sentence description of your program. ...