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.
