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
