On Jan 8, 2014, at 10:17 AM, Andrew Grieve <[email protected]> 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.)
