Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (nike.apache.org: domain of cmarcelk@gmail.com designates
 209.85.213.49 as permitted sender)
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 6.6 \(1510\))
Subject: Re: Review Request 16701: Add --searchpath option for local plugin
 search path
From: Marcel Kinard <cmarcelk@gmail.com>
In-Reply-To: 
 <CABiQX1Vu-52soZq0rkMRTikMDrD+QPpswwxm7Jg-sTUNcYe2MA@mail.gmail.com>
Date: Wed, 8 Jan 2014 12:02:58 -0500
Content-Transfer-Encoding: quoted-printable
Message-Id: <CAA50715-BFCA-4792-8AF9-4629A7C9DCEF@gmail.com>
References: <20140107214145.1151.95389@reviews.apache.org>
 <CAHcDwFy=w0sg0zMKLMCnqnNGxjzcrHRnPjMrQ=G19yWKR38eHw@mail.gmail.com>
 <CA+GVa3ZFMDOTqKY6ihcZy=GBqFUM_bEfiB0BL78-8nM-Xs4DBg@mail.gmail.com>
 <CAEeF2Tf8JS-fRcaoVSBVCU+Gjvg8SdeR2OX28U_SuvaBusm-ig@mail.gmail.com>
 <CABiQX1Vu-52soZq0rkMRTikMDrD+QPpswwxm7Jg-sTUNcYe2MA@mail.gmail.com>
To: dev@cordova.apache.org


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 ~=3D doc/help.txt), and =
detailed paragraphs and concepts explained outside the command (man =
pages ~=3D cordova-docs). What we have know is basically that.

> Some ideas for improving how we document / spec out new flags /
> features / settings to CLI:
>=20
> 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.)=