cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Posener <rposen...@gmail.com>
Subject Re: [DISCUSS] Cordova Style Guide
Date Wed, 27 Jan 2016 04:23:31 GMT
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 <rsalva@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:rposener8@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 <nikhilkh@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:rsalva@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:rposener8@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 <dblotsky@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-unsubscribe@cordova.apache.org
> > For additional commands, e-mail: dev-help@cordova.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
> For additional commands, e-mail: dev-help@cordova.apache.org
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message