I'd propose that we at least look into what it would take to write the auto-upload script with the mindtouch API. Radhika and I have already given much thought to the requirements. Is there someone with programming experience on this list who'd be willing to volunteer to work with me on that?
More replies also inline. https://cwiki.apache.org/confluence/display/CLOUDSTACK/Functional+Requirements+for+Documentation+Publishing+Tool > -----Original Message----- > From: Joe Brockmeier [mailto:j...@zonker.net] > Sent: Friday, August 17, 2012 7:39 AM > To: cloudstack-dev@incubator.apache.org > Subject: Re: FW: [WEBSITE][DOCS] Publican-based docs publishing? > > 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. > I am 98% certain that it is fine to keep docs on any site we want, as long as we link to it from our Apache project site. > > To carry over the features to Apache infrastructure, we'd have to have a > MindTouch install & license, and have someone maintain it. The current MindTouch install & license, which includes support, is provided by "a major sponsor of this project" and as far as I know (from asking them directly) they have 100% commitment to continue to provide it. If it ever goes away, we can move the content then. > 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. > The message, while alarming, is in error, and will disappear. I received assurances yesterday from Mark H that the license has been renewed. > > > 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. > Sorry, I should have been more clear. I only mentioned these features in order to point out that MindTouch also has them, in case anyone worried we would not get those cool features if we did not go with the publican generated site. By the way - you don't have to sell me on publican being pretty cool. I love its support for multiple languages, branding, etc. It has some quirks, but overall I've been happy using it. > 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. > I use the tags myself as part of the doc infrastructure. They feed into macros that provide useful site features. > > > 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. > Yes, and we absolutely need it. I'm proposing only using docs.cloudstack.orgfor the "formal" documentation. > > > 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, Joe, I can see why - it's easier and it's clearly inside Apache. Many of the arguments for the publican-generated path boil down to "it's easier for us." Easier not to have to keep track of reader comments, easier not to write a script, etc. I tend to look at it from the point of view of the users. This would be replacing an interactive and highly customizable site with admittedly nice-looking but static HTML. In general, yes, I am in favor of making my own job easier -- up to the point where it negatively affects users. I think it's worth some effort to make our documentation site more awesome. I'm willing to continue to put in that effort. > 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 > Check out http://docs.cloudstack.org/CloudPortal_Documentation/Billing_in_CloudPortal/About_Billing. This is part of the pilot project I did when I first selected these tools (I was the only person responsible for docs at that time). You won't see much of this yet in the cloudstack area of the site, since we just now got the point where we can do it on a larger scale. Jessica T. CloudStack Tech Pubs
