[
https://issues.apache.org/jira/browse/CB-5122?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13809643#comment-13809643
]
Mike Billau commented on CB-5122:
---------------------------------
bq. Not sure I understand "collapse," but if you mean simply copying the
README content into the doc (either one-time or dynamically), then I don't
agree.
The problem with the README.md files is that sometimes there will be duplicated
information in either the README or some guide, such as most of the
cordova-android README.md being duplicated in the Android Platform Guide, or
missing information, such as the registry commands and proxy settings for
cordova-cli being located only in the CLI's README.md.
bq. I suggest we get rid of "Platform Guide" & instead feature a "SoAndSo
Installation Guide", applicable to both CLI & shell workflows...
I think that we definitely need to revamp the individual Platform Guides and
remove any workflow related information. It should just talk about how to
install the platform SDKs and anything else common to both workflows (getting
signing keys, etc.) It should say something like "Now that you have installed
**Platform X** SDK, you can create an app using either _link to CLI guide_ or
_link to plugman guide_"
bq. ...then a separate "SoAndSo Development Guide" detailing the actual shell
workflow, corresponding to the current "Command-line Utilities" page
If you are suggesting multiple guides for each platform ("Android Development
Guide", "iOS Development Guide") then I think I agree. The problem will be not
reproducing the plugman documentation. I think we should have a high level
"Using Plugman" guide that details all of the common pieces of the shell
workflow and plugman API (the missing counterpart to "The Command-line
Interface" guide). Then we can add any platform-specific steps or information
for this shell workflow in these platform-specific "SoAndSo Development Guide"
- such as logging capabilities, anything unique in the "Command-line Utilities"
section, and all of the information about loading a project into an IDE. Then
go back to the "Using Plugman" guide and insert a bunch of warning and
pointers.
bq. Not sure I agree naming the CLI guide to "CLI Workflow", if that's what
you're suggesting. It implies a parallel set of "Workflow" topics elsewhere.
Agree. I'm not trying to suggest we call it the "CLI Workflow", I was just
using that phrase because that's what we were all throwing around on the ML. I
do think that this guide is sorely lacking a parallel doc though, but that will
be rectified when we expand the Using Plugman guide.
> Document supported workflows
> ----------------------------
>
> Key: CB-5122
> URL: https://issues.apache.org/jira/browse/CB-5122
> Project: Apache Cordova
> Issue Type: Bug
> Components: Docs
> Affects Versions: 3.1.0
> Reporter: Mike Billau
> Assignee: Mike Sierra
>
> Based on the recent discussion here [1]we should document the two different
> supported Cordova workflows: using the CLI, and using plugman and bin
> scripts.
> Some of this documentation already exists but needs to be clarified and
> improved:
> {{Overview guide --> "Development Paths" section}}. This talks about getting
> started with the CLI and then mentions that you can switch to the
> platform-specific SDK tools. This section should be rewritten to make it
> clear that there are two distinct workflows, and that both are okay and
> supported. It could list out some pros and cons of each workflow (I'm sure we
> won't have any trouble finding those ;)). It should be prescriptive in that
> users should be following one of the two workflows, but it shouldn't make any
> statements about which is better.
> {{"The Command-line Interface" guide}} --> The "CLI workflow" guide. It
> generally looks complete except for some missing functionality that is
> documented in the CLI's README.md file (tests, hooks, some commands (serve),
> some merges info).
> {{Platform Guides --> (Platform) --> (Platform) Command-line tools}} --> Each
> platform has a "Command-line tools" doc that explains all of the command line
> tools for that project and how to use them. We need to go through these
> guides and verify that they are up to date and include all of the lower level
> command line tools and scripts. It should read like a tutorial in the same
> way that the Command-line Interface guide does.
> {{"Using Plugman to Manage Plugins"}} First, this guide needs to get exposed;
> I can't find any way to get to this guide from the docs and even had to ask a
> user how she managed to find it (a link from Plugman's readme!). This guide
> needs to be expanded quite a bit; we can probably fold most/all of Plugman's
> README.md file into this guide since it will be platform agnostic.
> I think those are the only pieces in the docs that need to be changed.
> [1] http://callback.markmail.org/thread/5nr7dgkquse4gdkl
> [2]
> http://cordova.apache.org/docs/en/edge/guide_overview_index.md.html#Overview
> [3] http://cordova.apache.org/docs/en/edge/plugin_ref_plugman.md.html
--
This message was sent by Atlassian JIRA
(v6.1#6144)
