Updating Getting Started documents

[Becky Gibson <gi...@gmail.com>]

I have an updated Getting Started document for iOS that has received
favorable reviews.  However, it is 11 pages long and fairly detailed.  I'm
not sure if we want to include that on the documentation site.  I was
thinking that we could leave the basic getting started on the documentation
site with a link to the more involved document.

My thought was to attach the more involved pdf to a page in the wiki but
this doesn't keep it in source control.   Is that an issue?   I used pages
to write the doc and could export it to a Word format if necessary and
commit it to source control.

I'm interested to know what folks think as I will likely be able to work on
this over the Holidays.

The basic questions are:
1) should we include more involved documentation in the Getting started
section of docs.phonegap.com? (I could possibly work on updating the
Android version as well)
2) If we do want the more involved docs but not on the docs site, where
should it live?
3) what format - pdf, pages, doc?
4) where should it be commited - cordova-docs, cordova-<platform>

thanks,
-becky

Re: Updating Getting Started documents

[Shazron <sh...@gmail.com>]

Not being open sourced (editable) is definitely an issue. Any way you could
do it in Markdown? That way we can generate whatever formats needed.

1) Definitely - whatever makes it easier for devs to get started
2) Not in favour of external site for this, see (1)
3) Editable text, pref. Markdown
4) cordova-docs


On Thu, Dec 20, 2012 at 12:37 PM, Becky Gibson <gi...@gmail.com>wrote:

> I have an updated Getting Started document for iOS that has received
> favorable reviews.  However, it is 11 pages long and fairly detailed.  I'm
> not sure if we want to include that on the documentation site.  I was
> thinking that we could leave the basic getting started on the documentation
> site with a link to the more involved document.
>
> My thought was to attach the more involved pdf to a page in the wiki but
> this doesn't keep it in source control.   Is that an issue?   I used pages
> to write the doc and could export it to a Word format if necessary and
> commit it to source control.
>
> I'm interested to know what folks think as I will likely be able to work on
> this over the Holidays.
>
> The basic questions are:
> 1) should we include more involved documentation in the Getting started
> section of docs.phonegap.com? (I could possibly work on updating the
> Android version as well)
> 2) If we do want the more involved docs but not on the docs site, where
> should it live?
> 3) what format - pdf, pages, doc?
> 4) where should it be commited - cordova-docs, cordova-<platform>
>
> thanks,
> -becky
>

Re: Updating Getting Started documents

[Becky Gibson <gi...@gmail.com>]

Ok, thanks for the feedback.  I'll work on updating for 2.3 and converting
it to markdown over the holidays and post a pull request to give folks a
chance to review.

-becky



On Thu, Dec 20, 2012 at 4:27 PM, Marcel Kinard <cm...@gmail.com> wrote:

> Some possibilities to bounce around:
> - collapse your detailed info into the existing Getting Started guides.
> Then there is a single guide per platform and the info isn't spread out
> across multiple places (even though it may be unevenly detailed across
> platforms). This implies markdown and cordova-docs.
> - rename the existing Getting Started guides into QuickStart guides, and
> your doc becomes a new longer Getting Started. Host it in cordova-docs, and
> it gets published to the docs site. This implies markdown and cordova-docs.
> - your doc becomes the long version of Getting Started. Could be hosted on
> apache.org, could be any format you want such as pdf.
>
>
> On 12/20/2012 3:37 PM, Becky Gibson wrote:
>
>> I have an updated Getting Started document for iOS that has received
>> favorable reviews.  However, it is 11 pages long and fairly detailed.
>>
> Personally, I like the detail. If it is structured well, users can skip
> anything they don't need. Does anyone think your detail is not useful or
> complicating?
>
>  I'm not sure if we want to include that on the documentation site.  I was
>> thinking that we could leave the basic getting started on the
>> documentation
>> site with a link to the more involved document.
>>
> Personally, I like having all the documentation in basically one place.
> Less fragmentation, easier to navigate, easier to keep consistent. Are
> there different audiences or circumstances in which having 2 forms of
> getting-started is valuable?
>
>  My thought was to attach the more involved pdf to a page in the wiki but
>> this doesn't keep it in source control.   Is that an issue?
>>
> Because docs assume a point-in-time reference to the functioning code
> (describing how it works), to me it makes sense to put the docs in one of
> the existing git repos. Then the docs and code are always sync'd.
>
>  1) should we include more involved documentation in the Getting started
>> section of docs.phonegap.com? (I could possibly work on updating the
>> Android version as well)
>>
> Getting the same level of detail on other platforms would be goodness.
> Better educated users, smoother startup for them.
>
>  2) If we do want the more involved docs but not on the docs site, where
>> should it live?
>>
> I'd suggest defaulting to the docs site. Is there a reason it should be
> somewhere else?
>
>  3) what format - pdf, pages, doc?
>>
> I'd suggest it depends on where the readable content it is hosted, and
> what kind of control you want on edits.
>
> Bottom line, I think Shaz's reply is spot on. Convert to markdown and put
> in cordova-docs. So then should your content be collapsed or separate from
> the existing Getting Started? I'd suggest collapsed.
>
> -- Marcel Kinard
>

Re: Updating Getting Started documents

[Marcel Kinard <cm...@gmail.com>]

Some possibilities to bounce around:
- collapse your detailed info into the existing Getting Started guides. 
Then there is a single guide per platform and the info isn't spread out 
across multiple places (even though it may be unevenly detailed across 
platforms). This implies markdown and cordova-docs.
- rename the existing Getting Started guides into QuickStart guides, and 
your doc becomes a new longer Getting Started. Host it in cordova-docs, 
and it gets published to the docs site. This implies markdown and 
cordova-docs.
- your doc becomes the long version of Getting Started. Could be hosted 
on apache.org, could be any format you want such as pdf.

On 12/20/2012 3:37 PM, Becky Gibson wrote:
> I have an updated Getting Started document for iOS that has received
> favorable reviews.  However, it is 11 pages long and fairly detailed.
Personally, I like the detail. If it is structured well, users can skip 
anything they don't need. Does anyone think your detail is not useful or 
complicating?
> I'm not sure if we want to include that on the documentation site.  I was
> thinking that we could leave the basic getting started on the documentation
> site with a link to the more involved document.
Personally, I like having all the documentation in basically one place. 
Less fragmentation, easier to navigate, easier to keep consistent. Are 
there different audiences or circumstances in which having 2 forms of 
getting-started is valuable?
> My thought was to attach the more involved pdf to a page in the wiki but
> this doesn't keep it in source control.   Is that an issue?
Because docs assume a point-in-time reference to the functioning code 
(describing how it works), to me it makes sense to put the docs in one 
of the existing git repos. Then the docs and code are always sync'd.
> 1) should we include more involved documentation in the Getting started
> section of docs.phonegap.com? (I could possibly work on updating the
> Android version as well)
Getting the same level of detail on other platforms would be goodness. 
Better educated users, smoother startup for them.
> 2) If we do want the more involved docs but not on the docs site, where
> should it live?
I'd suggest defaulting to the docs site. Is there a reason it should be 
somewhere else?
> 3) what format - pdf, pages, doc?
I'd suggest it depends on where the readable content it is hosted, and 
what kind of control you want on edits.

Bottom line, I think Shaz's reply is spot on. Convert to markdown and 
put in cordova-docs. So then should your content be collapsed or 
separate from the existing Getting Started? I'd suggest collapsed.

-- Marcel Kinard