Stream: wg-cli

Topic: clap-doc


CreepySkeleton (Mar 25 2020 at 09:08, on Zulip):

(Just thinking aloud, feel free to join)

CreepySkeleton (Mar 25 2020 at 09:13, on Zulip):

I doubt that attracting extra attention to certain functions will fix the situation unless it's based on statically significant data, which we don't have.

A FAQ (this is essentially what @pksunkara proposes), in order to be useful, needs to focus reader's attention on the minority of topics that are asked most, leaving everything else out of sight.

To identify these commonly asked topics, we would need to gather significant number of help requests/complaints. So far, we've only had 10 or so. And they are fairly broad; I recall conflicts, requires, raw, groups, aliases, yadda, yadda. We don't have the data to write a useful FAQ at this point.

CreepySkeleton (Mar 25 2020 at 09:16, on Zulip):

Alternative proposal: encourage users to help each other with simple questions (like, what do I use to express "any of those, but not others?"). I think we should aggressively advertise the gitter chat.

CreepySkeleton (Mar 25 2020 at 09:17, on Zulip):

And only if the community haven't come up with anything satisfying, tell them to go to the issue tracker. This should significantly reduce the load for maintainers.

CreepySkeleton (Mar 25 2020 at 09:19, on Zulip):

Of course, this doesn't' mean that the doc is perfect and needs no improvement.

CreepySkeleton (Mar 25 2020 at 09:20, on Zulip):

I mean, the documentation is mostly fine, it's just there's a lot of it. Users, as @spacekookie pointed out, get drowned in it.

CreepySkeleton (Mar 25 2020 at 09:23, on Zulip):

We need... well , ideally, we would need a concise list of... pointers?

CreepySkeleton (Mar 25 2020 at 09:26, on Zulip):

It's like, we've already had a road, now we need waymarks.

CreepySkeleton (Mar 25 2020 at 09:26, on Zulip):

Any ideas?

CreepySkeleton (Mar 25 2020 at 09:26, on Zulip):

Also, the point of many of our user being newbies.

CreepySkeleton (Mar 25 2020 at 09:29, on Zulip):

Maybe some sort of book describing the process of an application creation.

CreepySkeleton (Mar 25 2020 at 09:30, on Zulip):

It should touch on most requested (except, as I said, we don't really know what those are) conflicts, subcommand, alisaes, requirements. Anything else?

pksunkara (Mar 26 2020 at 14:08, on Zulip):

I think we should do both, add a minimal FAQ and encourage users to participate in community chat

spacekookie (Mar 30 2020 at 14:15, on Zulip):

So I think an FAQ is a really good idea, and we should look through the docs that already exist and see how they can be made easier to navigate. I feel like maybe reducing the README down to a minimal example that people can just copy and paste in most situations, and then moving stuff into a docs folder tree (or wiki) might be a good idea.

I for one usually end up looking for the same three things that are kinda buried in the hay stack

spacekookie (Mar 30 2020 at 14:15, on Zulip):

Or well...markdown stack :P

CreepySkeleton (Mar 30 2020 at 14:26, on Zulip):

Shortening the README? Yes please. It's so long and looks so close to a documentation that some (I repeat, not enough data to make actual claims here) people confuse it with the actual documentation/examples.

CreepySkeleton (Mar 30 2020 at 14:27, on Zulip):

We can write a FAQ based on experience of our own, and then correct it as the we receive feedback.

CreepySkeleton (Mar 30 2020 at 14:28, on Zulip):

I for one usually end up looking for the same three things

Those being?

pksunkara (Mar 30 2020 at 23:04, on Zulip):

I am currently talking to someone about activating the discussions feature for our github repo. Hopefully that might help.

Last update: Jun 05 2020 at 22:30UTC