Mailing-List: contact cloudstack-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cloudstack-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of jessica.tomechak@gmail.com
 designates 74.125.82.175 as permitted sender)
MIME-Version: 1.0
In-Reply-To: 
 <7A92FF96DF135843B4B608FB576BFC3E012D9D670A41@SJCPMAILBOX01.citrite.net>
References: 
 <CAKprHVZS3W12=B1x114d1ZCD1jRYnWuL8e+P6163PPSBT34Gzg@mail.gmail.com>
	<20120816213847.GC24150@kodos>
	<CAKprHVbUgO9iexf4kme_vaa71uKH=Fs2NCJ9EG1NkhAeeYAfXA@mail.gmail.com>
	<CAKprHVZnu_aBJanFiNqDqGtW-tD7hQpoJp_aU3nfF2_wynDNKQ@mail.gmail.com>
	<7A92FF96DF135843B4B608FB576BFC3E012D9D670A41@SJCPMAILBOX01.citrite.net>
Date: Fri, 17 Aug 2012 00:26:54 -0700
Message-ID: 
 <CA+y6+xEdaGw+o17FS+Gf8s0J--BfuEN=JitGGNdov9x9jPP=mg@mail.gmail.com>
Subject: Re: FW: [WEBSITE][DOCS] Publican-based docs publishing?
From: Jessica Tomechak <jessica.tomechak@gmail.com>
To: cloudstack-dev@incubator.apache.org
Content-Type: multipart/alternative; boundary=f46d044401d0a0718f04c77115d4

--f46d044401d0a0718f04c77115d4
Content-Type: text/plain; charset=ISO-8859-1

On Thu, Aug 16, 2012 at 11:55 PM, Jessica Tomechak <
Jessica.Tomechak@citrix.com> wrote:

> You are proposing doing away with docs.cloudstack.org in favor of
> basically static HTML on the web. Do you want to go without the ability to
> tag, comment, provide a graphical front page, etc.?
>
>
> Jessica T.
> CloudStack Tech Pubs
>
>
> -----Original Message-----
> From: David Nalley [mailto:david@gnsa.us]
> Sent: Thursday, August 16, 2012 3:23 PM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: [WEBSITE][DOCS] Publican-based docs publishing?
>
> On Thu, Aug 16, 2012 at 5:45 PM, David Nalley <david@gnsa.us> wrote:
> > On Thu, Aug 16, 2012 at 5:38 PM, Joe Brockmeier <jzb@zonker.net> wrote:
> >> On Thu, Aug 16, 2012 at 03:46:12PM -0400, David Nalley wrote:
> >>> What do folks think of presenting our 'official documentation' in
> >>> this manner? Is it something worth pursuing? I was thinking having
> >>> this be a docs/ subdirectory on the project site (e.g.
> >>> incubator.apache.org/cloudstack/docs, is there a better place for it?
> >>
> >> The only question that comes to mind is how this is going to work
> >> with multiple releases? Any challenge in having 4.0 and eventually
> >> 4.1 or 5.0 (or whatever) living side-by-side?
> >
> > They live side by side, I'll update the site momentarily with multiple
> > versions so you can see.
>
>
> You should be able to see how multiple versions behave now. I added a
> '4.0' doc to the list.
>
> http://people.apache.org/~ke4qqq/docs/
>
> --David
>

David, are you are proposing that we do away with http://docs.cloudstack.org
?

Do we want to go without the ability to tag, comment, like, provide a
graphical front page, auto-generate Related Topics lists based on tags,
assemble FAQs from contributed pages, and other cool features the current
docs.cloudstack.org offers that I haven't even had time to investigate yet?
This site can offer multiple language versions as well as keeping docs for
multiple software versions.

My plan, which I sent to this list very early on*, was to keep
docs.cloudstack.org and link to it from the project website. I have a
graphic artist standing by to help make this site look amazing, to match
the CloudStack UI. This becomes even more important when we use URLs within
the site as the destination for context-sensitive help links. Currently the
site is pretty much in the out-of-the box template that came with the tool.
Example page:
http://docs.cloudstack.org/CloudPortal_Documentation/Billing_in_CloudPortal/About_Billing
.

The upside of doing a simple publican Publish As Website is that it is
simple to implement, and we can definitely do it in time for 4.0.

To get HTML into docs.cloudstack.org, we'll need to write some code to take
our generated HTML output from the docs build and use the
docs.cloudstack.org site's API to copy the updated HTML to each page, as
well as set the appropriate tags. Writing such a script is probably not
difficult, but still it's a script we might not have for 4.0 unless someone
volunteers to create it quickly. That's why the CloudStack portion of
docs.cloudstack.org doesn't yet look like the sample page above. We needed
our XML and continuous build in place first, and we now have that. Now we
can start to auto-upload.

I admit there are pros and cons to each approach, though it's obvious which
I favor. I just wanted to be sure we are all aware of the alternatives and
discuss those pros and cons before a decision is made.

* See Re: FW: [PROPOSAL] Further refinement of CloudStack modules... on
6/13/2012.

Jessica T.
CloudStack Tech Pubs

--f46d044401d0a0718f04c77115d4--