help with Cordova doc on the apache web (Was: Hello)

[Patrick Mueller <pm...@gmail.com>]

On Wed, Jan 11, 2012 at 09:39, zoe slattery <ap...@gmail.com> wrote:

> Hi - I was looking at your web site yesterday and wondering if I could
> help at all? I just talked to Pat and we kicked a few ideas around which we
> agreed to summarise on the list.
>

I think I'm most interested in figuring out how we're going to put what
content where.

For example, the PhoneGap API doc [1] seems like something we'd like "at
Apache".  But where?  The CMS?  The wiki?

Let's assume it's the CMS.  And that we will continue to programmatically
generate the API doc.  What does that process look like?  doc maintained in
git, then a build process pulls that, runs it's build, then publishes to
the CMS.  Do we have to go through SVN, the staging server, and then the
actual server?

Lots of low-level questions, obviously :-)

Looking at a higher-level, perhaps we should just figuring out:

1) what the options are for publishing content at Apache
2) figure out what content we actually want at Apache

For 1), I know about wikis and the CMS.  That's it, right?  I guess we need
to factor in that we still ship doc in the releases as well.

For 2) we can start by doing an inventory of current phonegap.com pages to
see what we want moved over.  And making sure we can copy it over, legally.
 Do we want to export the current wiki [2] over as a snapshot?

[1] http://docs.phonegap.com/en/1.3.0/index.html
[2] http://wiki.phonegap.com/

-- 
Patrick Mueller
http://muellerware.org

Re: help with Cordova doc on the apache web (Was: Hello)

[Jukka Zitting <ju...@gmail.com>]

Hi,

On Wed, Jan 11, 2012 at 4:23 PM, Patrick Mueller <pm...@gmail.com> wrote:
> Let's assume it's the CMS.  And that we will continue to programmatically
> generate the API doc.  What does that process look like?  doc maintained in
> git, then a build process pulls that, runs it's build, then publishes to
> the CMS.  Do we have to go through SVN, the staging server, and then the
> actual server?

See [1] for the recommended way of publishing generated stuff with the
Apache CMS.

Note that usually the official project site only contains static
documentation for existing releases of the product. Actively developed
documentation that refers to the latest trunk can reside elsewhere
like on a build server [2] or a wiki, and be just referenced from the
main project site.

> For 1), I know about wikis and the CMS.  That's it, right?

As mentioned above, documentation generated from sources in git or svn
can also be located on a build server for developer use. For example
the generated javadocs of the latest Apache OpenCMIS trunk are
available at [3].

> I guess we need to factor in that we still ship doc in the
> releases as well.

As noted by Ross earlier, anything that gets included in the release
packages we ship needs to be traceable back to a committer (and thus
an ICLA), which rules out an open wiki as the source repository for
such documentation.

[1] http://www.apache.org/dev/cmsref.html#generated-docs
[2] http://ci.apache.org/
[3] https://builds.apache.org/job/Chemistry%20-%20OpenCMIS%20-%20javadoc/javadoc/

BR,

Jukka Zitting