incubator-callback-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Filip Maj <...@adobe.com>
Subject Re: Your coding practices and documentation are not done well.
Date Sat, 14 Jan 2012 01:18:34 GMT


On 12-01-13 3:13 PM, "Peter Ehrlich" <peter.i.ehrlich@gmail.com> wrote:

>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.)

Peter, we hear you loud and clear. This was a pain point for the entire
PhoneGap crew as well and we fought really hard, together with the CouchDB
team and with the help of most/all of our Apache mentors to even get git
approved as an acceptable form of source control! This project would not
be at the level of popularity and exposure it currently enjoys without the
help of github and its community, so transitioning to us from github to
Apache infrastructure has been tough, but I know I am motivated to make it
as easy and close to github as possible in terms of collaboration and
exposure. If it's any solace, Apache git repositories that houses our code
are mirrored over to github.com/apache, and you can fork those repos and
send pull requests to that as you would with any other github repository.

>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.

Apache did, but git is now acceptable as of maybe a month ago. The
requirements to keep the code and other things like issue tracker and wiki
on Apache infrastructure, from my understanding, is more about legal
issues and less about control or anything else. Getting into Apache
guarantees fair governance of the project as well as project neutrality
which, in my mind, is more important than where the issue tracker is
(which can be solved with good documentation). I understand that github
and the community it harbours are extremely important assets for any open
source project, but in the long run the move to Apache will benefit us and
you. And trust me, we're not disappearing from GitHub!

>Here's how I would fix documentation:

These are great - thank you for these!

>
>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.

Totally. As soon as the new Apache-blessed wiki is online we are going to
do just that.

>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.

I would suggest that, because we'll be using an Apache wiki, we can
instead link to it from each project's README.

>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.

This seems pretty reasonable too. Given we have multiple repositories (one
for each platform), perhaps including a succinct version of this info in
each repo's README would suffice?

>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.

This is a great idea; however, not sure how the Apache "old guard" would
feel about this. I will volunteer to explore this option within Apache if
it's an option.

>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.

I think some kind of "feedback" widget on the docs site used to exist (it
would be visible on any page as a little tab on the side of your screen
that slides out), but has been since removed. My understanding is that
it's coming back soon.

>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.

I've started a new thread on the mailing list about how we can modify our
documentation repository to address this issue (as well as merging in the
various phonegap.com/start guides into the cordova docs repo). Hopefully
we can get to a consensus there and start making the necessary
modifications, and bring those online! If you have any suggestions, please
chime in on that thread so we can get some more movement on that one.

>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.

I'm always keen on seeing what people come up with :)


Mime
View raw message