I just did some working patching the Scalate soca and found it to be a nice system. Having the edits show up immediately rendered in a browser was quite nice.
On Friday, October 15, 2010, James Strachan <james.strac...@gmail.com> wrote: > On 13 October 2010 13:06, Gert Vanthienen <gert.vanthie...@gmail.com> wrote: >> L.S., >> >> In http://github.com/gertv/servicemix-documentation, I've been working >> at transforming our current Docbook-based documentation project into a >> Scalate based project. I've transformed all the existing DocBook >> sources into wiki markup and added Scalate templates for both HTML and >> PDF output. While it started more as an experiment for me, I think >> the end result looks OK and the Scalate-based template are a lot >> easier to work with than the DocBook XSL transformation. > > Awesome! > > After working with various documentation systems on different open > source projects over the last decade (to name a few: Forrest, > Codehaus, Confluence/AutoExport, webgen and now Scalate) I'm now > convinced projects should just store their site and docs inside the > same source control system as their code; so its easy to version & > branch - and avoid lots of "if version X then... ", "if version Y > then... " stuff in the docs. The docs you get with the project are > then relevant to the version you have! e.g. here's the versioned site > + docs for Scalate... > http://scalate.fusesource.org/versions/ > > Also I prefer to stay the hell away from XSL and spend most of the > time hacking simple wiki markup (either confluence or markdown > syntax). Finally contributions are very rare in documentation from non > committers (and anyone who provides a decent amount of docs as a patch > should be a committer anyway IMHO) - so the wiki isn't that big a deal > really; the actual committers typically would rather be able to edit > the docs using text editors (search & replace FTW!). Non committers > can trivially fork the repo in github and hack there and push changes > back. > > In addition with many systems like the Confluence AutoExport or even > WebGen; its kinda hard to edit a template/layout/nav bar and hit > reload in your browser and see what the site is actually going to look > like - which is very painful when editing docs and working on the > site. > > So while I'm hopelessly biased, the Scalate approach is now my > preferred approach for docs & websites for open source projects. > (WebGen is quite good though, but supporting Confluence (and having a > Confluence export) and having reload in a browser working are killer > features which make Scalate the natural choice for folks moving away > from Confluence). > > >> Now that Scalate 1.3 has been released, I would like to propose >> committing this experiment back into the documentation/trunk we have >> at Apache. I've been fixing up Scalate last weekend to allow using it >> in a WAR file deployed in OSGi, so by the next version of Scalate, we >> might even be able to ship our documentation as part of the >> distribution, perhaps as an installable feature so people can view the >> manual from their own ServiceMix instance. > > Awesome! I can imagine having a combination of 'web apps' and > 'documentation' increasingly; so we can reuse documentation with > things like installers or for browsing installed components & > endpoints or learning how to configure them etc. I can see much of the > documentation in ServiceMix being useful inside the servicemix web > console for example. > > -- > James > ------- > http://macstrac.blogspot.com/ > > Open Source Integration > http://fusesource.com/ > -- Principle Technical Writer Phone (781) 280-4174 Skype finnmccumial E-Mail emjohn...@fusesource.com Blog http://documentingit.blogspot.com/
