Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (athena.apache.org: domain of brian.leroux@gmail.com
 designates 209.85.128.179 as permitted sender)
MIME-Version: 1.0
Sender: brian.leroux@gmail.com
In-Reply-To: 
 <CADjNb+k3k+qP+4ybGraxxh3FvV6gT2iRz98fHu1wynd+v2eLwA@mail.gmail.com>
References: 
 <CAE6O_-bBtbfHAhXcxMuR6-umKiqwct1=U1Fia5HrqgVrAcZi8g@mail.gmail.com>
	<CAM2q_UwKcMVRCtPMe_OMvxj8JRczy=O474+2cSvZvkh2hD783w@mail.gmail.com>
	<CAOBL_k42M1HU15VszhtEB-bgJ8Jz0dsNSuyO68LKfd=fQUVeLg@mail.gmail.com>
	<CAE6O_-a2SiDgTznmkLN99t4TvRFCf1Q3XoTQ94XAU6DjgcjVEA@mail.gmail.com>
	<CABiQX1WZHyMphxKFxQ=UPHf8yFNVtzDZN8m=KJYY890TtjBnNA@mail.gmail.com>
	<CADjNb+k3k+qP+4ybGraxxh3FvV6gT2iRz98fHu1wynd+v2eLwA@mail.gmail.com>
Date: Wed, 23 Jan 2013 12:35:00 -0600
Message-ID: 
 <CADVgkyM+fqzG9mBW7NWqOCbqbwRyoXH00jiTJDxqK9jKJrfAsQ@mail.gmail.com>
Subject: Re: Getting Started (Android) feedback
From: Brian LeRoux <b@brian.io>
To: dev@cordova.apache.org
Content-Type: text/plain; charset=ISO-8859-1

Agree w/ this sentiment Becky. Of late, I've been of the opinion the
target audience for Cordova is and more advanced users and
accommodating the less technical user base is a job for the downstream
distributions. We're not doing a very good job of it here or in the
downstream at any rate.

I know it is Michaels plan to start working w/ more folks to revamp
the various docs. (At the trivial level we need to brand the PhoneGap
docs as such and get the Cordova docs hosted on cordova.io but there
is much, much more to do.)

To target those efforts I created a document for PhoneGap identifying
3 types of user:

- Web Professionals
- User Experience Professionals
- Devops and Platform Specialists

Web professionals can be experienced or new to HTML, CSS, and
JavaScript. User experience professionals may not necessarily have
coding skills but understand technology, interaction design, form,
flow, typography, information architecture, and so on. Devops and
platform developers typically code in systems languages to a
particular operating system or runtime in addition to scripting skills
for supporting automations such as continuous integration systems.

As much as makes sense we'll be contributing the docs updates to
Cordova, but other distributions will require specialized docs for
certain audiences. For example, devs creating CI systems using the
PhoneGap/Build API or UX folks prototyping in Dreamweaver.

On Tue, Jan 22, 2013 at 4:32 PM, Becky Gibson <gibson.becky@gmail.com> wrote:
> I know I'm late to the party but I have some concerns about the idea of
> providing only command line instructions.   I'm not sure what the plans are
> for detailed instructions but I'm not sure our current user base is going
> to be comfortable using the instructions currently in the readme in the
> cordova-cli repo.  Don't get me wrong,  I understand that the repo is for
> developers but I think we need to take a closer look at the current cordova
> user base and make a decision about what type of developer we want to
> support and how we want to support them.  Then we can craft the correct
> type of useful documentation.
>
> Based on what I see in the PhoneGap group, many users are very naive and
> have limited "hard-core" development skills.  Many are not familiar with
> IDE's let alone using the command line!   Maybe that is not the user base
> we want to encourage?  Perhaps we should be pushing those users to products
> built upon Cordova like IBM's Worklight or Adobe's Dreamweaver integration
> or others?  We really should be considering our audience as we make changes
> that affect the installation and use of Cordova.  I believe the goal of
> Cordova is to make building Mobile apps easier and we certainly have been
> pushing that idea at conferences.  And we do tell people that you just need
> HTML and Web skills.
>
> Yes, it is difficult to keep the documentation up to date when there are so
> many changes but it should be considered as part of making and scheduling
> changes.
>
> In addition, I think that we may need to continue to provide some level of
> detail about installing prerequisites.  For the IDEs there are generally
> fairly good installation documents available from other sources and we
> shouldn't try to replicate them.   For iOS we can point to the instructions
> provided by Apple.  For Eclipse we can hopefully find some third party
> instuctions or point to something at eclipse.org.  Many of our users need
> this level of hand holding.   However, point at nodejs.org and telling
> someone to install node could be daunting for some users  - the nodejs site
> is really geared for developers, not end users!
>
> Ok, I'm rambling.  The point I'm trying to make is I think we need to
> determine who the user base for Cordova really is,  clearly spell that out
> in the wiki or home page  and taylor our documentation and installation
> towards that user base.
>
>
>
>
> On Sun, Jan 20, 2013 at 9:12 AM, Andrew Grieve <agrieve@chromium.org> wrote:
>
>> Looking at the two guides right now, two things struck me as different:
>>
>> 1. Andrew's walks you through *how* to install all of the required tools,
>> we just say which tools to install
>> 2. Andrew's instructions go through the old way of setting up a project,
>> which is now out of date. But! Once going through them, you get a pretty
>> good idea of how Cordova works because he points out what all of the pieces
>> do. E.g. the jar is the native side, the www is your code, the manifest is
>> where your permissions go.
>>
>>
>> As for #1, I think the short version we have in our guide is sufficient,
>> and I don't like the idea of having it explained out more thoroughly
>> step-by-step, because it's then more of a pain to keep up-to-date.
>>
>> I can see us doing more in the area of #2 though. E.g. have a separate
>> guide that goes through all of the parts of an Android Cordova app, and
>> points out which ones you may want to touch at some point.
>>
>> I also agree that it might make things more clear to separate out IDE
>> instructions from the core command-line instructions. I don't think we
>> should remove them though, since the IDE is the harder thing to figure out
>> usually :P.
>>
>> Perhaps to tie in these external tutorials, we add a note at the bottom
>> saying that if you still need help, to search for external tutorials /
>> youtube walkthroughs / link to the user forums? We could also mention which
>> versions of Cordova have had changes in steps, so that they don't follow
>> old tutorials like the one that was pointed out.
>>
>>
>>
>> On Sat, Jan 19, 2013 at 12:42 PM, Shazron <shazron@gmail.com> wrote:
>>
>> > Just at a glance, I suppose his tutorial has more screenshots and steps.
>> We
>> > could take the good and extract the incorrect and fix those I suppose.
>> >
>> > As for command line, that is definitely where we are going and if we
>> remove
>> > Eclipse instructions (which third-party bloggers can fill the gap) we
>> > should point them to the alternative instructions. Which brings me to the
>> > next question -- should all platforms remove IDE specific instructions?
>> > There are some things in iOS currently that we can't do command line (at
>> > least with the current tools), for example deploy to device.
>> >
>> >
>> > On Sat, Jan 19, 2013 at 9:11 AM, Joe Bowser <bowserj@gmail.com> wrote:
>> >
>> > > Andrew Trice's tutorial is out of date and is technically wrong. The
>> > > Android target for a project should always be set to the latest.  I
>> > > would agree with Don about not having Eclipse in our instructions,
>> > > except that I don't have that much confidence in the command line
>> > > tools on Windows to do that.
>> > >
>> > > I think the question that should be asked is why users find Trice's
>> > > tutorial better? I don't think it has anything to do with the content,
>> > > since the content is the same other than the part where you select
>> > > your target manually in Eclipse.
>> > >
>> > > On Sat, Jan 19, 2013 at 8:40 AM, Don Coleman <don.coleman@gmail.com>
>> > > wrote:
>> > > > I think it's better to remove Eclipse from the instructions.
>> > > >
>> > > > Have users build and deploy with ./cordova/run.
>> > > >
>> > > > Suggest using a text editor like Sublime Text to edit assets/www.
>>  Note
>> > > > that Eclipse or IntelliJ IDEA works if they'd prefer. Link to
>> external
>> > > > articles with more details.
>> > > >
>> > > >
>> > > >
>> > > >
>> > > > On Sat, Jan 19, 2013 at 10:45 AM, Shazron <shazron@gmail.com> wrote:
>> > > >
>> > > >> Some feedback from users:
>> > > >> https://groups.google.com/d/topic/phonegap/K9uv3Hc-EfI/discussion
>> > > >>
>> > > >> Their feedback is, Andrew Trice's tutorial is way better than our
>> > > official
>> > > >> one:
>> > > >>
>> > > >>
>> > >
>> >
>> http://www.adobe.com/devnet/html5/articles/getting-started-with-phonegap-in-eclipse-for-android.html
>> > > >>
>> > > >> What do you guys think? We can contact Andrew to maybe donate his
>> > > content
>> > > >> to Apache Cordova and we can update/adapt it.
>> > > >>
>> > >
>> >
>>