Documentation Structure
rhauch Dec 2, 2011 12:58 PMOne of the things we want to do for ModeShape 3.0 is move our documentation into the new JBoss.org documentation system. It's a Confluence installation and that means the users can comment on each page and the community can collaborate on the documentation. One other benefit is that we can have separate documentation for each release, and each release has a set of documents and nice TOC view; see the Infinispan documentation as an example. Overall, there are lots of benefits to moving to this new system, and very few cons (the biggest being having to learn the new system, which I don't think is going to be a big deal).
We've had our Getting Started and Reference Guides for a long time (since the 1.x days), but they're starting to show their age. We've made sure that the content is up-to-date with each release, but I don't think they're structured well and that they make it difficult for people to find answers to particular questions. Anecdotally, our users are asking more and more questions that are answered in the docs, so I can only conclude that users are not really reading the documentation as much as they should. And while that might be a general condition of software users, what we can do is make our documentation as usable as possible. And IMO our current documentation is not as usable as it needs to be. It needs some love and attention.
So rather than simply load our existing documentation into the new Confluence system, I think we should take this opportunity to rethink what we want our documentation to be.
What would like to see in our documentation? What have you found difficult?
Keep in mind that there are multiple ways of deploying ModeShape (embedded vs. app server), and each has it's own techniques. The JBoss AS 7 integration will be fairly significant, and managing that will be very different than other embedded cases (since we're whole-hog adopting the AS7 management/admin system). There's also our JDBC driver. And the RESTful and WebDAV services.