Ryan, Thanks for your kind words of encouragement. I have just uploaded my documentation style guide with comments to JIRA CB-10448 <https://issues.apache.org/jira/browse/CB-10448>. Please let me know what you think.
Regards Rob Regards *Rob Posener* 0419 012 627 On 27 January 2016 at 14:06, Ryan J. Salva <rsa...@microsoft.com> wrote: > Rob, > > 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. > > rjs > > > > -----Original Message----- > From: Robert Posener [mailto:rposen...@gmail.com] > Sent: Tuesday, January 26, 2016 6:33 PM > To: dev@cordova.apache.org > 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. > OK? > > Rob > > PS I'm in Australia (Sydney) so there may be a time lag between your > requests and my responses. > > > > > Regards > *Rob Posener* > 0419 012 627 > > On 27 January 2016 at 13:08, Nikhil Khandelwal <nikhi...@microsoft.com> > wrote: > > > 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] > > https://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fissue > > s.apache.org%2fjira%2fsecure%2fRapidBoard.jspa%3frapidView%3d108%26vie > > w%3ddetail%26selectedIssue%3dCB-10348&data=01%7c01%7crsalva%40microsof > > t.com%7c63966dfb5ac6455d95bc08d326c250db%7c72f988bf86f141af91ab2d7cd01 > > 1db47%7c1&sdata=NxXSGuc1unEAwKArfjPW9%2b0o%2fAaj1%2fGDOGNmNJC6fOA%3d > > [2] > > https://github.com/cordova/cordova-discuss/pull/31/files?short_path=b5 > > 89504#diff-b589504f1eedbd87c81f38ce873d5d85 > > [3] https://github.com/apache/cordova-docs > > > > Thanks, > > Nikhil > > > > -----Original Message----- > > From: Ryan J. Salva [mailto:rsa...@microsoft.com] > > Sent: Tuesday, January 26, 2016 5:54 PM > > To: dev@cordova.apache.org > > 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 [mailto:rposen...@gmail.com] > > Sent: Tuesday, January 26, 2016 5:45 PM > > To: dev@cordova.apache.org > > 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 <dblot...@microsoft.com> > > 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: > > > https://na01.safelinks.protection.outlook.com/?url=https%3a%2f%2fiss > > > ue > > > s.apache.org%2fjira%2fbrowse%2fCB-10448.&data=01%7c01%7crsalva%40mic > > > ro > > > soft.com%7cdb95d5df3d7545a54e1008d326bb7ca9%7c72f988bf86f141af91ab2d > > > 7c > > > d011db47%7c1&sdata=iBwCcS7cBzD%2fnsj79mTPQCFzWUTUUm%2fkBlSTPmBBBFk%3 > > > d > > > > > > Kindly, > > > Dmitry > > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org > > For additional commands, e-mail: dev-h...@cordova.apache.org > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org > For additional commands, e-mail: dev-h...@cordova.apache.org >
