search

epage / clapng

A full featured, fast Command Line Argument Parser for Rust
docs.rs/clap
Apache License 2.0
0 stars 0 forks source link

Add some sort of Guide in addition to docs.rs and examples #144

Open epage opened 2 years ago

epage commented 2 years ago

Issue by CreepySkeleton Wednesday Mar 18, 2020 at 00:29 GMT Originally opened as https://github.com/clap-rs/clap/issues/1752

What's wrong

It's been consistently being reported that our documentation is hard to navigate. Many people come to the bugtracker to ask for a feature that is already implemented or can be achieved by using a set of related features.

It is apparent to me that our docs talk about "what" only, but they also should tell "how" and "why". The docs.rs is mostly about possibilities, but what people (especially beginners) seek for is applications and common usages.

Examples help, but they can only cover so much. Also, examples show "how", but they can hardly explain "why". Sometimes it's hard to generalize a specific example further.

I would like to stress the "beginners" part here. The first thing many Rust newbies that come from other languages look for is "command line parser". Obviously, they get directed here (also to getopts, but clap is the most popular choice). What they need is a guide about

Instead, they get a few quick examples from the Readme, a few more elaborative examples, and a big set of methods they need to glue together not yet knowing how things work here. This makes the learning curve even more abrupt.

How to fix

We need something like rust-cli book, but centered on CLI args' parsing part and clap-specific.

epage commented 2 years ago

Comment by pksunkara Friday Mar 27, 2020 at 13:04 GMT

As first part, can we emphasise gitter chat and have a small FAQ in the issue template?

epage commented 2 years ago

Comment by CreepySkeleton Friday Mar 27, 2020 at 14:05 GMT

I'd rather go with something like

MAKE SURE YOU HAVE ASKED YOU QUESTION ON <link to chat> FIRST. 
Maintainers are few, and their mental health is fragile.

Or something like that. Concise, draws attention, and, I hope, not rude.

epage commented 2 years ago

Comment by pksunkara Friday Mar 27, 2020 at 14:06 GMT

The first sentence is enough.

epage commented 2 years ago

Comment by CreepySkeleton Friday Mar 27, 2020 at 14:07 GMT

But the second explains why 😏

epage commented 2 years ago

Comment by pksunkara Friday Mar 27, 2020 at 14:07 GMT

I don't think we need to.

epage commented 2 years ago

Comment by CreepySkeleton Friday Mar 27, 2020 at 14:08 GMT

Anyway. I'm leaving the decision to you.