-
Notifications
You must be signed in to change notification settings - Fork 418
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
Manual/Quick guide: better support for first time users #890
Comments
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? |
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:
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:I tried to address this issue already while updating the quick guide to the execute API, that's what I came up with:
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:
Checksum
commandIn short I would propose to move the
Checksum
example from the chapterIntroduction
to the chapterGetting 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):
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?
The text was updated successfully, but these errors were encountered: