Documentation: improvements #1171
Conversation
Codecov Report
@@ Coverage Diff @@
## master #1171 +/- ##
=========================================
Coverage 94.29% 94.29%
Complexity 455 455
=========================================
Files 2 2
Lines 6661 6661
Branches 1792 1792
=========================================
Hits 6281 6281
Misses 102 102
Partials 278 278 Continue to review full report at Codecov.
|
|
Merged. Very nice, thank you! |
| How it works: annotate your class and picocli initializes it from the command line arguments, | ||
| converting the input to strongly typed values in the fields of your class. | ||
| === Sample application | ||
| Let's get started by looking at minimal picocli-based command line application. This fully working sample app may be used to calculate the checksum(s) of one or more file(s) given as command line parameter(s): |
There was a problem hiding this comment.
Overall, I am not sure about the changes to the Introduction section.
On the one hand, the additional structure of the Features and Sample Application subsections is nice in that it signals what is coming to readers.
On the other hand, naming the subsection "Features" suggests that what is mentioned in that paragraph are the only features that are noteworthy. Or at least the most important ones. I would like the reader's first impression to be different: "this is just a small taste of what is available".
Many users mention that what they like about picocli is how full-featured it is.
I want to emphasize that in the user manual. That is also why I used Features instead of Table of Contents as the header for the TOC. Strictly speaking, you are correct: this is the Table of Contents. But by labeling it "Features", followed by 200+ entries, the first impression that people get, looking at this document is "wow, this thing has a lot of features". That is what I was aiming for, at least... :-)
There was a problem hiding this comment.
On the one hand, the additional structure of the Features and Sample Application subsections is nice in that it signals what is coming to readers.
That was my intention, and I still consider this an improvement.
On the other hand, naming the subsection "Features" suggests that what is mentioned in that paragraph are the only features that are noteworthy. Or at least the most important ones. I would like the reader's first impression to be different: "this is just a small taste of what is available".
I see the point. What about "Selected features", "Features (amongst many others)", "Features that make picocli unique, ...
Many users mention that what they like about picocli is how full-featured it is.
I want to emphasize that in the user manual. That is also why I used Features instead of Table of Contents as the header for the TOC. Strictly speaking, you are correct: this is the Table of Contents. But by labeling it "Features", followed by 200+ entries, the first impression that people get, looking at this document is "wow, this thing has a lot of features". That is what I was aiming for, at least... :-)
Accepted. We can revert 'Table of contents' back to 'Features', no problem with that.
There was a problem hiding this comment.
How about Introduction for the section, and Overview for the first subsection (instead of Features)?
|
|
||
| TIP: Picocli also provides a <<Programmatic API,programmatic API>>, separately from the annotations API. |
There was a problem hiding this comment.
I am in two minds about this change.
It is more detailed, and in a way, the example now has become something of a mini-tutorial by itself.
This is useful, but perhaps not at this place in the manual: in the introduction we still want to sell the product. At this stage, readers are not yet convinced that they want to use picocli.
I would like casual readers to be able to glance at the example and think to themselves: "that looks easy! I can definitely do that! Wow, that is like a full app in 25 lines of simple code, nice!" 👍
It is true that there is a lot of detail to be explained, but we have the whole rest of the manual to do that... 😄
There was a problem hiding this comment.
I am in two minds about this change.
It is more detailed, and in a way, the example now has become something of a mini-tutorial by itself.
I see the point.
This is useful, but perhaps not at this place in the manual: in the introduction we still want to sell the product. At this stage, readers are not yet convinced that they want to use picocli.
O.k. What about leaving the introductory sample as is and moving the 'mini tutorial' to the quick guide (chapter 2.1 Example). We can then place a link in the manual: "For a detailed explanation of the sample application, you may refer to the <<link,quick guide>>.
It is true that there is a lot of detail to be explained, but we have the whole rest of the manual to do that... smile
And additionally, we do have the quick guide ;-)
If you agree to that, I'm willing to modify my PR in the sense described above.
There was a problem hiding this comment.
Yes, that's a great idea!
The Quick Guide is currently just a shorter version of the full manual, but I like the idea of developing it into something that stands on its own more.
This would be a nice step in that direction.
No description provided.