9 Replies Latest reply: Dec 7, 2011 4:00 PM by Randall Hauch RSS

Documentation Structure

Randall Hauch Master

One 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.

  • 1. Re: Documentation Structure
    Horia Chiorean Master

    I've seen a lot of questions coming up around the configuration of various connectors. I know that in the reference doc there is a dedicated sub-section for each type of connector.

     

    I would create an "examples" top-section for each type of connector, showing various configuration options for that connector (also based on what has been discussed in the forum so far) but without explaining all the configuration options of that connector (instead a link to the ref guide).

  • 2. Re: Documentation Structure
    Kosta Krauth Newbie

    I spent the last couple of days digging through the getting started and reference guides, and I second what Horia has suggested. Each connector should ideally have two snippets that shows how to configure it via XML and how to configure it programatically. This is especially true for the federation connector which is a little more involved in setting up.

     

    From my perspective, the first thing that every new user will be interested in doing is creating some repository sources and projections since this is the main aspect that separates ModeShape from other JCR implementations. If it requires constant switching between the getting started guide, getting started examples and reference guide, then there is definitely room for improvement.

     

    In addition, I think there should be a more thorough example of how to remotely configure hosted instances. I initially started with a hosted instance on JBoss AS6, but due to the fact that my repository sources are dynamic, I couldn't pre-configure them using a static XML file. Therefore I decided to create an application that runs ModeShape embedded simply for purpose of initializing repository sources dynamically - and I don't think that this is an ideal approach.

     

    Overall, the reference and getting started guides did very well in helping me understand the concepts and architecture behind ModeShape, but I found them slightly lacking when it came down to implementation details.

  • 3. Re: Documentation Structure
    Randall Hauch Master

    Thanks for all the comments so far. They're exactly what I was hoping to hear.

     

    I'd also like to start brainstorming the structure of the documentation, so to that end I've come up with an initial strawman proposal. Please give us your thoughts and suggest ways we can improve it -- or even suggest a completely different structure!

     

    • Getting Started - This document shows how to quickly get started using ModeShape and introduce some of the features and concepts of ModeShape. It'd cover how to download, build, and run the ModeShape example applications. Ideally each of the examples would be small. Might these be "quickstarts", or should quickstarts be completely separate from the getting started examples?
    • Introduction to JCR - What is JCR? What are JCR repositories, and how do they differ from other data storage systems? This should explain concepts and show how to use the different parts of the API. It should also describe the grammars for the query languages, with some good example queries. There's not a lot of good user-level information about JCR out there.
    • The Basics of ModeShape - This would be mostly a concept document that talks about how ModeShape works from a user's perspective. This is where we'd say how and why ModeShape uses Infinispan (since that's pretty important), and the various ways that ModeShape & Infinspan can be deployed and clustered. We'd probably describe how configuration works (conceptually), and what can be configured, but I'm thinking that we won't show configuration examples here since the details of how the configuration is specified differs between AS7 and embedded cases. This doc would introduce the ModeShape-specific features, like sequencing, federation, query language enhancements, and our small API extensions (like registering node types in CND files). The "Introduction to JCR" document will cover most of the "how to", so hopefully we don't have much code snippets here.
    • ModeShape in JBoss AS7 - Installing ModeShape into AS7 will be significantly different than embedding: we're adopting the AS7 configuration system for all administration and monitoring. So configuration will be all about how to use the AS7 admin tools to configure ModeShape. We'll even have an RHQ plugin that can be used to monitor and manage a whole cluster. Also, Infinispan is already installed into AS7, so we'll have to talk about how to create caches for ModeShape. Our JDBC driver will also be installed, but will have to be configured as a typical JDBC Data Source. Plus, our web apps will be installed out of the box.
    • Embedding ModeShape - Describe the ways of using ModeShape within web applications and custom applications. This should outline our configuration files, how to use Infinispan's configuration files (including using a remote data grid), the ways of managing the repository instances (via a JcrEngine instance, the RepositoryFactory, or JNDI factory), how to get the repository instances, how to monitor repositories, how to set up clustering, etc. Lots of best practices.
    • Extending ModeShape - Detailed 'how-to' for writing extensions like sequeners, text extractors, connectors (whatever form they tak), etc.
    • Glossary - a simple collection of terms and definitions
    • FAQ - start accumulating questions and answers, with links to any related forum discussions.
    • Videos and Presentations - largely a set of links to other places.

     

    This structure would exist for each minor release. When we release, we basically copy the most recent docs into a new area for the next release. (Again, this is all made possible by the JBoss Confluence installation.) The only time we need to go back to change older releases is to fix documentation errors or make things more clear. (Note that even now we rarely go back and change the documentation for older releases, so this wouldn't be a big change.)

     

    Thoughts?

  • 4. Re: Documentation Structure
    Randall Hauch Master

    I just uploaded the 2.7 documentation to the Confluence system. Have a look, and let me know what you think.

     

    Note that this is simply an import of the DocBook code we have in our Git repository, so it is nothing like what I'd like to see for ModeShape 3.0. However, it does give a pretty good example of the new documentation system, the ability to comment, the ability to edit (for those that have privilege), etc.

  • 5. Re: Documentation Structure
    Van Halbert Apprentice

    seeing Unable to render embedded object: File () not found in some of the GSG.

  • 6. Re: Documentation Structure
    Van Halbert Apprentice

    I like it.

  • 7. Re: Documentation Structure
    Randall Hauch Master

    The missing images are fixed.

  • 8. Re: Documentation Structure
    Kosta Krauth Newbie

    I like the proposed structure. I think it's especially important to separate the chapters that deal with ways of running ModeShape (deployed vs embedded) as it can be a bit unclear what are the benefits and disadvantages of each. Perhaps it could be worthwhile adding a short paragraph/chapter on why you'd chose one over the other - i.e. Can dynamic configuration be achieved in deployed mode? Can you run webdav/rest modules in embedded mode? etc.

     

    The JCR specific documentation should prove very valuable as well. I found the Jackrabbit documentation to be very sparse, while most blog posts and articles deal with very high level concepts and give just a brief overview of JCR architecture without going into details. Definitely scope for improvement there.

     

    As far as writing custom connector goes, I believe that the importance of well documented code for existing connectors should not be ignored. Having one well commented feature-complete connector for a version control system should be an excellent reference when creating connectors for other VCSs. I will likely be tasked with writing a simple read-only connector for an in-house VCS and the first thing I intend to look at is the existing SVN connector. An overview of ModeShape specific connector interfaces and how they map to JCR APIs would be great as well.

     

    That's all that comes to mind for the time being, if I think of anything else I'll add it on later

     

    Message was edited by: Kosta Krauth

  • 9. Re: Documentation Structure
    Randall Hauch Master

    Those are all excellent suggestions and comments, so thanks! (And keep them coming.)

     

    A few responses ...

     

    Perhaps it could be worthwhile adding a short paragraph/chapter on why you'd chose one over the other - i.e. Can dynamic configuration be achieved in deployed mode? Can you run webdav/rest modules in embedded mode? etc.

    Excellent point. And the answers to your questions are "Yes" and "No".

    The JCR specific documentation should prove very valuable as well. I found the Jackrabbit documentation to be very sparse, while most blog posts and articles deal with very high level concepts and give just a brief overview of JCR architecture without going into details. Definitely scope for improvement there.

    We can pretty easily identify the obvious JCR API topics (how to obtain a Repository instance, when are long-lived sessions useful, etc.), but just the JCR tutorial is going to be a big undertaking. Like you said, it will be very useful the more complete it is. And it's one area that JCR users (not just ModeShape contributors) can help.

     

    I will likely be tasked with writing a simple read-only connector for an in-house VCS and the first thing I intend to look at is the existing SVN connector. An overview of ModeShape specific connector interfaces and how they map to JCR APIs would be great as well.

    We'll announce on this forum when the 3.0 connector framework starts solidifying, and we'd love to hear your feedback when the time comes. And in the meantime, we'd love to hear about your requirements (perhaps on a separate thread). For example, will the content in the VCS be exposed as files and folders, or is there a specific set of node types that will be used? Will you need to expose the version history of the VCS through JCR's version history mechanism? How long can information be cached before discarding it and accessing the VCS? Does the VCS provide a hook to notify ModeShape of changes? Anything you can share would be greatly appreciated.

     

    Our goal is to dramatically simplify the code for connectors, while at the same time taking advantage of the integral Infinispan cache (for caching purposes, not just for storage).

     

    An overview of ModeShape specific connector interfaces and how they map to JCR APIs would be great as well.

     

    I agree. The good news here is that most of the ModeShape 3.0 extension API (like sequencers, text extractors, etc.) will be changed to directly use the JCR API. The connector API might still be dealing with internal concepts/structures, so we'll definitely have to explain the mapping well.