cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marcel Kinard <cmarc...@gmail.com>
Subject Re: Review Request 16701: Add --searchpath option for local plugin search path
Date Wed, 08 Jan 2014 17:02:58 GMT

On Jan 8, 2014, at 10:17 AM, Andrew Grieve <agrieve@chromium.org> wrote:

> Yeah, I think we're still as a team doing a bit of a bad job of documenting
> features.

I also think that there are shortcomings in the user-facing documentation. It's definitely
better than it used to be, but there is still real room for further improvement. Just yesterday
I was helping a Cordova user who is smart with moderate experience sort through some usage
issues, because they didn't see clear documentation on their topic. I looked at the docs,
and it was there, but in a non-obvious place and in pieces. To me that's a sign that there
is more work to be done ;-)  I don't think we are bad at docs, we're just not as consistent
as we should be. IMHO, to the non-expert user, good docs make all the difference. Last week
at an Android meetup an app developer was telling me that he ditched Cordova and went with
another cross-platform framework because he was frustrated by the Cordova docs. The docs for
the other framework were more clear.

Perhaps I'm biased by Linux, but for the CLI docs I like the Linux model: summary help embedded
in the command (-h ~= doc/help.txt), and detailed paragraphs and concepts explained outside
the command (man pages ~= cordova-docs). What we have know is basically that.

> Some ideas for improving how we document / spec out new flags /
> features / settings to CLI:
> 
> 1 - Add a wiki page for each

I would prefer to see the finished docs go into doc/help.txt and cordova-docs. What kind of
content would you intend to go in the wiki? To me the wiki is more for developers of Cordova
about the development process, whereas users of Cordova should need to look only at --help
and cordova-docs to use Cordova.

> 2 - Add a section within doc/help.txt in addition to a one-line --flag
> usage description

+1

I've stumbled across CLI flags that weren't documented in doc/help.txt before (and I added
them). And perhaps doc/help.txt could have a pointer to cordova-docs.

> 3 - Attach a full flag description to the JIRA issue

During design/discussion of the flag implementation, ok. But after it is implemented, --help
and cordova-docs should be the authoritative version.

> 4 - Email out full flag descriptions to the ML

Or perhaps just putting it in Jira is sufficient, assuming most people subscribe to receive
all the Jira updates (or am I the only one who does that?). Then it is in context with the
rest of the work. But yeah, addition of new flags should be on the ML according to the Apache
Way.

> 5 - Add text to cordova-doc's plugman/CLI guides

+1

> so I think it'd be good to try and do #3 for
> spec'ing out the intended help.txt text, and then have help.txt be the
> authoritative version going forward.

+1

If we can reach consensus on these kind of documentation guidelines, would putting them on
our wiki help us all be more consistent in doing them? (The goal being to improve the quality
of our docs.)
Mime
View raw message