cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ryan J. Salva" <>
Subject RE: [DISCUSS] Cordova Style Guide
Date Wed, 27 Jan 2016 03:06:52 GMT

Your proposal makes total sense and I'd, personally, be happy for you to start with a revitalized
style guide. 

To encourage frequent updates to the docs, our process to-date has been intentionally light-weight.
I think one concern among the community will be: if there's overhead for documentation changes,
will it discourage contributors from making updates?

Really, I think what we need is someone to take the reins as a copy editor. We are primarily
a community of very pragmatic coders. The subtleties of prose all too often escape our best
intents. Having said that, we have identified documentation quality as a major cause of dissatisfaction
and prioritized it in the roadmap. Perhaps with a style guide and passionate contributor in-place,
we can collectively improve the process and public-facing documents.


-----Original Message-----
From: Robert Posener [] 
Sent: Tuesday, January 26, 2016 6:33 PM
Subject: Re: [DISCUSS] Cordova Style Guide

Gerday again,
Thanks for the quick replies.
I was already aware of the 3 links above (as I said, "I've been watching for a while").
I must not have been clear in in my email... So I'll be a little more precise, BEFORE any
effort is expended on revamping the documentation, we need to agree what the documentation
style standards are to be.  In my humble opinion, the current documentation style standards
are insufficient and need a revamp.  If we don't do this, we will end up with a mashup of
different looking documents that look like they have been cobbled together over time by a
lot of well-meaning amateurs.
The new (agreed IA) is terrific.  The next step is to agree the standards and the process
for maintaining (reviewing, promulgating, inculcating, making all committers aware of, updating
existing documents to, revising, etc).
My guess is this means raising a JIRA for this activity.


PS I'm in Australia (Sydney) so there may be a time lag between your requests and my responses.

*Rob Posener*
0419 012 627

On 27 January 2016 at 13:08, Nikhil Khandelwal <>

> Rob,
> I appreciate your enthusiasm. Cordova docs need a lot of improvement. 
> We did a survey in October and 70% of negative comments focused on 
> problems with our docs.
> Committers at Microsoft are pushing hard to improve the Cordova docs - 
> but we need a lot of help from the community. We are using a JIRA 
> Kanban board [1] that we are using to track documentation tasks/bugs. 
> This captures all the work referenced in creating a new information 
> architecture for our docs [2].
> There are a number of ways to help in this effort:
> - Pick one of the JIRA bug/task to improve the current docs. Start 
> small - any help here would be fantastic!
> - Review doc updates for styling etc. issues. PRs are filed against 
> cordova-docs repo [3].
> - File JIRAs for issues that you find in current docs.
> - Identify high priority topics that are currently missing and need to 
> be added.
> - Help organize document scrubs within the community.
> It's critical for a dev platform to have good docs and our goal is to 
> make that happen for Cordova in the upcoming months.
> [1]
> w%3ddetail%26selectedIssue%3dCB-10348&data=01%7c01%7crsalva%40microsof
> 1db47%7c1&sdata=NxXSGuc1unEAwKArfjPW9%2b0o%2fAaj1%2fGDOGNmNJC6fOA%3d
> [2]
> 89504#diff-b589504f1eedbd87c81f38ce873d5d85
> [3]
> Thanks,
> Nikhil
> -----Original Message-----
> From: Ryan J. Salva []
> Sent: Tuesday, January 26, 2016 5:54 PM
> To:
> Subject: RE: [DISCUSS] Cordova Style Guide
> Rob,
> Any contributions you can provide would be most welcome... especially 
> if you can help us apply that style guide to existing docs. We're 
> making a big push to improve the documentation this year, but it's 
> hard work and often gets prioritized below things like bug fixes to the actual framework.
> It all starts with a pull request :-)
> rjs
> -----Original Message-----
> From: Robert Posener []
> Sent: Tuesday, January 26, 2016 5:45 PM
> To:
> Subject: Re: [DISCUSS] Cordova Style Guide
> Gerday, Dmitry,
> I'm a bit of a documentation pedant.
> I have been "monitoring" Cordova development for a few months now, 
> with the initial intent of wanting to contribute to improving the 
> documentation (and then, perhaps to contributing to the code base).
> The thing that has struck me in this time is that there appears to be 
> NO documentation style standards.  Yes, the documents you reference go 
> some of the way towards what I am looking for but they could be a lot 
> better (eg, is it "E.g.,", "eg,", "e.g.,", is it "Cordova" or 
> "cordova", is it "database" or "data base", do you put a comma before 
> the "and" in the last of a list of comma separated items (eg, is it 
> "a, b, c, and d" or is it "a, b, c and d"), do we employ USA-English or UK-English (or
both), etc).
> Further, it appears that some contributors "pick up" others with their 
> code style standard breaches (I have seen "please insert a space 
> here", "please lint this", etc), but I rarely see anyone picking up 
> documentation style standards beaches.
> Without letting my ego get in the way, I'm happy to contribute a 
> suggested list of style standards (that I use when developing Android 
> and Windows apps using Cordova) as well as acting in a Quality 
> Assurance role with the documentation.
> As you probably know, the Cordova documentation is quite regularly 
> critcised all over the web.  Rather than be just another one of these 
> criicisers, I'm happy "to put my time where my mouth is" and 
> contribute.  I (and others) believe we can do a lot better here.  What do you think?
> Rob
> Regards
> *Rob Posener*
> 0419 012 627
> On 27 January 2016 at 11:55, Dmitry Blotsky <>
> wrote:
> > Hey folks,
> >
> > I know we used to have a style guide on the wiki, but that seems 
> > long dead. I created a JIRA for a new Cordova-wide style guide, 
> > covering most of the languages we use (feel free to add others). The JIRA is here:
> >
> > ue 
> >
> > ro 
> >
> > 7c 
> > d011db47%7c1&sdata=iBwCcS7cBzD%2fnsj79mTPQCFzWUTUUm%2fkBlSTPmBBBFk%3
> > d
> >
> > Kindly,
> > Dmitry
> >
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:
View raw message