incubator-callback-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Ehrlich <peter.i.ehrl...@gmail.com>
Subject Re: Your coding practices and documentation are not done well.
Date Fri, 13 Jan 2012 23:13:41 GMT
Hi everyone, and thanks for your responses

 > For now, opening a bug up on "improve documentation" with as much
 > excruciating detail as you are willing to give us, would be quite useful.

Moving all issue tracking and documentation to Github would be an extremely
good decision.  If you want to attract new developers, and crowdsource your
documentation (and this is one of the only ways to get consistently good
documentation), the Apache software will not do.

Github is the most popular tool, and its growing.  I myself and those I
know use it not only for finding code, but as a key part in
the decision making process when considering new software.  The number of
open/closed issues, as well as how they are handled and their age, tells
more about the health repository than anything else I know.

Github provides and even playing field.  As issues of all apps are
presented equally, developers know how to interpret what they see.  Equally
good software on any other system wouldn't be as good, for the simple
reason that the users --those people you want to see as contributors to
Cordova-- are already familiar.

Github has a company behind it, doing an unparalleled job on its issue
tracker and wiki.

Nobody's going to contribute so much as a bug report if they don't know
their work is valued.  Compare the jira, where a bug report is fairly stark
isolated, to a github bug report which is seen in the context of the other
reports, and tied to the code and people that are involved in it, and well
indexed by google.

Github is a resumé item for contributors, just as stack overflow is.  When
someone helps the project on github, their commits and comments continue
give them credence in their profession, and github will continue to find
new ways to do this.  Visibility of work is an incredibly motivating force
(I feel that I can speak at least for beginning coders.)


If Apache demands that the usage of their proprietary software be put over
an intrinsically better system, be it github or anything else, then they
are foolish.


Here's how I would fix documentation:

Start with a Steve Jobsian passion for deleting things.  Mark the entire
wiki (http://wiki.phonegap.com/w/page/16494772/FrontPage) for deletion, and
work on moving the good stuff to new locations (see below).  This is not
software you want to be working with-- even the official rails wiki (
http://wiki.rubyonrails.org/) is singularly outta date and useless.

Cordova is a complex and multi-layered project.  I think I see natural
divides in to device-specific implementations, a shared javascript api, and
thirdly strong design patterns shared across devices.  This third category
includes plugins and things such as whitelist implementation; I imagine it
will grow more as Cordova matures.

Move device-specific documentation to their github readme.md files, and if
necessary, specific wiki pages.  This is not a difficult job, especially if
you already have the repo forked.  Make sure that every device repo has its
wiki enabled, this is important, as it's not a default.

Pick one repository (perhaps a new callback/cordova replacing
callback/phonegap) to be the master repo.  Link all other repos here for
general links, discussions, help, and wiki.  On this page include how to
contribue, the location of the google groups, your twitter handle, links to
plugins and the API docs, and so on.

I don't know enough about the shadowing to say how easy all this is to do,
but the effect would be powerful.  Licenses are sounding like a non-issue;
but if that's not the case, get in touch with github.  Surely its a problem
they've run in to before, and either would have idea for a solution, or
maybe could be talked in to rolling some custom features for you and anyone
else needing licensing.


I haven't tested yet, but try checking to be sure its never more than 2
clicks to go between what you're reading and a way to fix what you're
reading.

Oh, and looks like bug report about the whitelist got taken up, sweet!  As
it stands there's no apparent place to add documentation about the feature,
but I believe the google group post will show up well on google.

And I didn't say this earlier, but thanks for all the hard work.  I'm
excited to see what's coming up in 1.4!

Finally, I've been toying somewhat with a jquery wrapper library, with a
hope of resulting in a simpler intuitive API.  It's only involving photo
capturing for now, but hopefully I can make it public and useful to others
soon.

Cheers,
--Peter





On Fri, Jan 13, 2012 at 4:26 PM, Patrick Mueller <pmuellr@gmail.com> wrote:

> On Fri, Jan 13, 2012 at 15:03, Peter Ehrlich <peter.i.ehrlich@gmail.com
> >wrote:
>
> > The bottom line is that I think the product you're all working so hard to
> > produce would benefit strongly from a concentrated focus on cross-team
> > communication/synchronization, documentation, and cross-platform
> > documentation.  (Or maybe I'm just a pampered Rails developer?)  I might
> > even suggest moving from the existing wiki system to the github one, so
> as
> > users will be encouraged to contribue through having existing accounts.
> > --Peter
>
>
> I think providing more documentation, especially regarding
> platform-specific issues (whitelists, etc), is something we should be
> doing.  Could you open a bug?
>
>    https://issues.apache.org/jira/browse/CB
>
> In terms of engaging more folks to help with the documentation, there are
> three different ways I see us providing doc at Apache:
>
> - the main site: http://incubator.apache.org/callback/ (will be renamed
> cordova some day)
> - documentation shipped with releases
> - the wiki: (does not yet exist AFAIK)
>
> For the first two items, my understanding is that only committers will be
> able to author that.  The wiki is a little looser, but I don't completely
> understand the rules yet.
>
> We currently have shadows of the git repos at apache, at GitHub.  Here's
> the doc project, which contains the documentation shipped with the
> releases:
>
>    https://github.com/apache/incubator-cordova-docs
>
> We are still working out the process for how to accept commits from folks;
> you would need to an have an ICLA on file -
> http://www.apache.org/licenses/icla.txt , but we're hoping you can fork
> the
> GitHub repo, and somehow issue a pull request to make a contribution.
>
> For now, opening a bug up on "improve documentation" with as much
> excruciating detail as you are willing to give us, would be quite useful.
>
> --
> Patrick Mueller
> http://muellerware.org
>

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