Manual/Quick guide: better support for first time users

[deining]

While answering #878, I realized, that both user manual and quick guide could be improved. Goal should be to get first time users started as quickly as possible.
Thinking back to my first time contact with picocli I remembered it wasn't straightforward for me to get things up and running, either. Don't get me wrong: The picocli manual is very complete, concise and was/is of great help for me in many cases. However, it has -well- manual-style, and this might a hindrance for first time users. Luckily I see good chances to iron this out quite easily. Here are my thoughts/comments on this:

I assume first time users start reading at the beginning of the manual. Currently, the outline is:

• Introduction
• Getting started
• Options and parameters

What I'm missing here: nowhere in the manual, first time users are introduced to the concepts of commands and how to annotate them. This is a shortcoming IMHO that may lead to questions as exemplified in #878.

The introduction features the Checksum example, but it does not explain how to annotate command classes at all. All it states is:

How it works: annotate your class and picocli initializes it
from the command line arguments, converting ...

I tried to address this issue already while updating the quick guide to the execute API, that's what I came up with:

Create a class that represents your command and annotate
this class with @Command. Then, annotate the fields or
methods of the command class with @Option or @Parameters
to ...

IMHO, this should be reflected in the user manual, too. I doubt whether this is sufficient however.
This is what I would like to suggest/ see implemented:

a) Extend the 'Getting started' chapter like this:

• Getting started
  • Setting up your enviroment
    • Add as external dependency
    • Add as source
    • Annotation processor
  • Real word example: Checksumcommand

In short I would propose to move the Checksum example from the chapter Introduction to the chapter Getting started. The example should be explained in more detail there (going through the releveant lines of the source code step by step).

b) Add an additional chapter to the outline (optional):

• Introduction
• Getting started
• Commands
• Options and parameters

The Commands chapter should cover subcommands, too, since this is a common requirement for many command line apps (at least for me, see also #878).

Just my two cents, what do you think?

[remkop]

You raise a good point, but I need to think a bit more on how to solve/deal with it.

The problem in a nutshell is that people are smart but busy, and people don't read.

When people are very busy (and most people are) they just want to find a solution to their particular problem, right now, without having to read the whole manual first.

The introduction is designed for that: it deliberately skips over a lot of detail, just gives a very high-level overview, and as soon as possible shows an example. This example uses all the main features and should be enough for many people to grasp the main ideas and get started.

Subsequently I expect users to use the Table of Contents and browser search (with Ctl-F find) within the page to find documentation on the features they are interested in.

In the case of #878, the user did not know they were looking for commands/subcommands, and that makes it difficult because in that case, neither search nor the Table of Contents allow them to zoom in to the area of interest. However, I suspect this cannot be solved by improving the user manual. (Fortunately the user asked so we were able to point them in the right direction.)

What I'm thinking may help is other types of documentations, particularly short and focussed tutorials that cover one specific topic. I've been thinking to contact Baeldung to ask if they are interested in publishing a series of picocli tutorials (and hopefully also allow me to host them on picocli.info as well). I'm currently working on an article that I hope to get published on InfoQ, and my plan was to contact Baeldung after that. If you're interested in helping with these tutorials that would be great.

Thoughts?