Enhance getting started documentation

[JosiahParry]

I heard about clap through a youtube video.

I want to make a cli tool using clap, however I'm finding the documentation very sparse. While there are numerous examples, there is next to no written description of the examples, what each step is doing, etc.

In a related discussion someone linked to a Rust CLI Cookbook which is more along the lines of what I anticipate.

I'd suggest that the tutorials for clap be more thorough. The derive "tutorial" is not much more than an example program and provides little info to someone like me who is fairly early in their rust journey :)

Though, I will note that this seems to be an issue that is generally among all rust crates I've encountered. But clap is largely the most useful of them so far though :P

[epage]

How we view documentation is rooted in our own backgrounds. For example, I have to deal with the "curse of knowledge" where the tutorial seems obvious. Before that, I worked to fix the pitfalls I ran into when I was a new user of clap (and structopt, a project that was merged into clap). It'd help if i knew more about your background to understand what isn't working and why.

Some starter questions:

• How new are you to Rust?
• Have you used other derive APIs, like serde?
• What CLI previous CLI parsers do you have experience with?

I think I also saw you post on Mastadon about the sorry state of Rust documentation. Previously, it seemed like people instead would praise the state of documentation (except maybe changelogs), so I suspect there might be something more fundamental to how the Rust community has been working that isn't quite working out for you. So if you could also talk about your broader documentation concerns, it might help uncover some additional insights into how we can improve the documentation.

I can make some guesses as to what problem you had and throw some more stuff at it but I would like to make sure we are addressing actual problems and not make the documentation worse by belaboring points that aren't a problem.

[JosiahParry]

Hey @epage,

To answer your immediate questions: I've been programming in Rust for about 8 months now so fairly new in the scheme of things. I've not used serde's derive functionality, no. No other cli parses beyond the examples from The Book™.

I think you make a good point that this is really a problem with Rust documentation in general--some crates are better than others, though. Perhaps its the format of docs.rs that encourages a lack of documentation, I'm unsure.

I come from the R world where thorough documentation is part of the culture and frankly a requirement for publishing a package onto CRAN (the "official" R package manager). Packages typically include written examples in the README (which gets rendered as the home page of package sites) that describe the utility of the package, the main functions, and how to anticipate interacting with the tools. Additionally, there are typically 1 or more vignettes that describe a more complicated aspect of the package. Further, each function in the package is required to be documented with descriptions of the parameters (beyond the types that are required), the output (beyond the type), and an example of each function.

rlang is a good example of good developer-focused documentation with numerous vignettes and decent function reference.

Hands down, the best Rust crate documentation I've encountered is "ndarray for numpy users". Other approaches I've seen that are common small "books" such as the one for georust which has some examples but fails to describe how the crate is intended to be used.

Tokio is another example of a library that very thorough book-like docs which is great if you want to read a book but isn't great for getting started quickly. The "documentation" is a lot like other libraries that are structured like "You can do this" (massive code block) or you can even do this! (another massive code block). But in between those code blocks there is no description of the code, what it is doing, or description of why that code will let you do xyz.

Perhaps, this is an expectation of folks coming from other low-level languages that the only way to document is to just read source code and figure it out for yourself. But myself, as someone who is self-taught and comes from literally anthropology, sociology, and geography, a little bit of guidance goes a long way.

[JosiahParry]

Edit: maybe "hands down the best" was an exaggeration upon further review of the ndarray docs lol

[epage]

I want to be very clear, any confusion at your situation in my post is not meant to cast doubt on you and your experience but to call out gaps in understanding of your lived experience and where I want to better understand.

Perhaps its the format of docs.rs that encourages a lack of documentation,

I think one of the challenges in discussing this is the imprecision which can put people on edge. You are saying that rust lacks documentation but my perception has been that reference documentation is very common and with rustdoc you regularly see accompanying (short) examples. Were you intending to refer to the other types of documentation? This has been a long problem. Someone started looking at tackling it but since then their involvement in the community has dropped and no one has tried to take on that work since. If you are referring to reference documentation, I wonder where the gap is in our perceptions.

With that said, I feel like the README/summary you mentioned is commonly covered by the top-level module documentation in Rust projects, like ndarray, tokio, and regex. Is there something about these not covering those cases or are observing different sets of crates in terms of whether they do this or not?

A lot of projects do have richer examples (again, a built-in convention making it easy, like rustdoc) but they weren't tied into docs.rs by default. There is an experiment to link out to those examples for every API item that uses them. I just checked for some examples but it seems to have broken recently on my projects so nothing is showing up :/

As you mentioned, some projects have "books". I think serde is a great example where it covers a lot of topics that don't fit within reference documentation. When looking into documentation for clap, I got a lot of feedback from a vocal subset of users that they wanted a single place for documentation rather than having reference and other forms of documentation in two different places. I know I've run into problems with this with nom where I have a hard time finding the relevant information because I'm looking in the wrong place. As a maintainer, this also works well as there are tools native to my workflow to help me keep the documentation up-to-date.

And tying this back to clap, I would have assumed that clap would be filling what you say. The top-level docs say what it is, quickly show an example that demos the runtime behavior, links out to more complex examples (the cookbook) that categorizes things both by features and by familiar commands, links out to a very light tutorial, etc.

Perhaps, this is an expectation of folks coming from other low-level languages that the only way to document is to just read source code and figure it out for yourself.

Something feels very off here. Rarely do I see no documentation, leaving people to only look at the source. I'd say its rare that I need to dig into the source and its usually because I'm fairly off the beaten path that I can understand what I cared about being left out. I feel like there is something fundamental to our unique perspectives that we are missing, whether thats the type of crates we are looking at, or what is missing from the docs, etc.