As a writer and not much of a coder, I love the idea of a docuthon:) On Friday, October 15, 2010, Adrian Trenaman <trena...@progress.com> wrote: > Hi Eric, > > I'd be very happy to get the stuff out of confluence and into SVN as you > propose. I saw a post from James on Scalate, and I think that it would be > great way to leverage Scalate as part of our renovation. > > Possibly the most important things for me are: > > a) That it becomes part of source-code control. This makes documentation a > 'first class citizen' in our community, and allows talented writers to > contribute and become recognized committers. In the past, there has been > little incentive or recognition for writing documentation, and this will fix > that. > > b) That whatever format we use is easy-peasy to write, and lets us focus on > content/structure rather than formatting. > > On a related note, the documentation problem on the Apache site is, I feel, > doing the ServiceMix community a disservice - yet, thankfully, its not an > NP-hard problem to fix! To fix it fast, I'd like to propose a 'docuthon' > event. If someone can set out the structure of the documentation, and then > create a load of JIRA's for the individual sections/sub-sections that need to > be written, we could mobilize the community for a single week to stop coding > and get writing, for just one week. Then, someone in an 'editor' role can > pull it all together, clean it up, and enforce coherency. > > What do you think? > > On 15/10/2010 00:20, Eric Johnson wrote: > > I saw that there have been a number of starts for getting the project Web > site updated, but not a lot of forward progress. I'd like to help out and > have the time to get some of the work done. > > I like the proposal at http://servicemix.apache.org/home2.html. It does a > nice job of presenting a unified entry point and guiding a visitor to the > version of ServiceMix they want. The side menu could be de-cluttered allot. > Perhaps removing the documentation and component sections and adding short > sections for SMX3 and SMX4? > > For the version specific sub-sites there needs to be some re-org as well to > make it clear what information is for users and what is for developers. The > SMX4 stuff should probably be re-orged to remove the distictions between the > NMR, Kernel, and ServiceMix. > > As for the discussion about moving some of the documentation into DocBook, > or at least into something that can be versioned better, I can help with > that as well. There needs to be some distinction between what should be done > in the Wiki and what should be done in DocBook. IMHO user-facing, > authoritative content should be done in DocBook and technical articles, > knowledge base articles, FAQs, and more developer focused stuff should be > done in the Wiki. > > Would it make sense to move the main site pages out of confluence and into a > format that can be stored in SVN? Maybe use a tool like Scalate? > Cheers, > Eric J. > > >
-- Principle Technical Writer Phone (781) 280-4174 Skype finnmccumial E-Mail emjohn...@fusesource.com Blog http://documentingit.blogspot.com/
