cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marcel Kinard <cmarc...@gmail.com>
Subject Re: Updating Getting Started documents
Date Thu, 20 Dec 2012 21:27:29 GMT
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

Mime
View raw message