incubator-cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joe Brockmeier <...@zonker.net>
Subject Re: FW: [WEBSITE][DOCS] Publican-based docs publishing?
Date Fri, 17 Aug 2012 14:38:32 GMT
On Fri, Aug 17, 2012 at 12:26:54AM -0700, Jessica Tomechak wrote:
> David, are you are proposing that we do away with http://docs.cloudstack.org
> ?

I think this goes away one way or another with the transition of
*cloudstack.org to Apache. 

To carry over the features to Apache infrastructure, we'd have to have a
MindTouch install & license, and have someone maintain it. What David's
proposing comes with very little overhead.

Also note - I'm looking at the site now and we're getting a warning that
"the site has expired and will be disabled on August 22." So we need a
solution soonish, I think.

> 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.

In a follow-up to this discussion, David showed that it's pretty trivial
to have multiple versions living side-by-side. The docs were also
available in multiple language versions.

Tagging, commenting, liking - none of these seem like vital features to
me, but others can comment if they seem necessary. Note that maintaining
social features on the docs site expands the surface area for the
project to keep tabs on. 

Skimming through the site so far, I'm not seeing many comments or tags. 

> 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.

Yep! :-) 

It has other upsides, too:

- It does not require special infrastructure.
- It does not require a proprietary license.
- It is low maintenance.
- It fits with a single contribution pipeline rather than two or three.

Note that we still have the wiki for less formal documentation, too. 

> 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.

Indeed. I'm glad David started the thread so we can decide. Any other
thoughts, folks? I'm firmly in favor of the Publican-generated site, but
it's up to the project. If we do decide to go with a MindTouch based
docs site, though, we have to solve the licensing and infra issues ASAP.

Best, 

Joe
-- 
Joe Brockmeier
http://dissociatedpress.net/
Twitter: @jzb

Mime
View raw message