Now that the new JBoss.org site has been released, I'd like to take a moment to share some of my thoughts behind the design of the content.
History
I've worked at JBoss since May 2005, back when it was JBoss Inc. and we were busy breaking new ground with the introduction of JEMS and JBoss ON. As the lead consultant in EMEA I spent most of my time traveling around Europe, visiting clients to fix production issues and giving advice on development strategies. In addition to this I conducted Intro, Admin and Advanced training courses in many different countries and gave classes on migration techniques in India and the US.
This experience gave me a fantastic insight into how people were using JBoss software in a wide variety of environments and showed me where most of the difficulties occurred in using it productively. Not surprisingly the vast majority of these related to a disconnect between the documentation available to users on the website and the particular releases of the software they were using.
As implementation details often change substantially between versions, due to bug fixes and new features, it is often the case that information written about one version of a release no longer applies to the next. Without complete and accurate documentation for every release this leads to confusion for users who expect the software to behave according to outdated information in the wiki and forums. It is also the reason why people are sometimes advised to 'read the source'.
Related to this issue is the level of information provided. Developers often write documentation to describe new features they have added or the meanings of configuration parameters but do not have the time to step back and paint a wider picture. When learning about a new topic, or even trying to find out more details about a known topic, starting with a high level of abstraction and working downwards towards more detailed information always helps people to find what they are looking for more quickly and reliably.
Compounding these problems is the fact that open source releases occur very frequently and anyone can submit information to the wiki, forums and mailing lists at any time. As such it's critical that information is highly organized and can be navigated or searched easily if people are to find out what they need to know in a short space of time.
These concerns were addressed in our JEMS subscription offerings with the creation of reference and user guides written by the project leads, the addition of a rating system for the content in our wikis and forums, and an advanced search facility accessible from our customer support portal.
Future
In my new role at JBoss.org I aim to provide similar benefits to the community through the adoption of a set of guidelines for the development of new content:
1) Start at the beginning
This does not mean to say that learning must be slow. The steepness of the learning curve should be decided by the reader but information should always flow from a point where the majority of people understand what is being said. By always putting yourself into the mind of a new user and asking yourself "What is the most obvious question to ask at this moment?" you can create content that flows naturally and avoids confusion by giving readers what they expect. This not only prevents people from asking basic questions later on but also allows them to ask more informed questions sooner. If a concept is fundamentally flawed or has a better alternative, then being able to question this early on can help to prevent unnecessary work and wasted effort.
An example of using this guideline can be found on the Home page where I have defined the purpose of the JBoss.org website. This clearly states our main objectives and provides a context around which the rest of the site can be understood. It also acts as a way to set expectations so that the reader knows what they are getting into.
2) Make things as simple as they can be but no simpler
OK, I can't take credit for this :) but it's very important to keep in mind. If you start to introduce ideas and concepts before the time is right then people will either get confused, bored or worse still both!
An example of where I have applied this is with the Project category descriptions, found by clicking on the category headings on the Projects page. Here I take a few sentences to explain the most important features of each project and highlight how these are useful. This is all that's needed at this point to get people interested and decide whether they want to find out more.
Note: It's always easier to ask for more information about a particular topic than to search through a mass of unrelated information. Easier in this sense means that you simply choose whether to find out more or not. It may be quicker to find specific information using a search engine but you then have to make choices about the search results which is not always straightforward and often breaks your train of thought.
3) Be concise
Don't use 20 words to say something when 10 will do. This skill is often overlooked when people produce documentation quickly and it takes patience to develop a clear writing style. Often you may rework a paragraph or sentence many times over before you settle on an accurate and concise version. The investment in time to do this will be paid back many times over by communicating the content more quickly to readers, especially if they number in the hundreds or thousands.
4) Be consistent
To prevent confusion and allow users to navigate easily through the site, it is important that the content for projects remains as consistent as possible. The objective is not to prevent each project from developing a personality of its own but rather to ensure that there is a basic level of consistency upon which users can rely. For example each project should clearly explain how to download the source code, build it and run any unit tests that are provided.
5) Be clear with your use of terminology
Understanding the importance of words when creating and using terminology is crucial for establishing concepts and explaining ideas. This is demonstrated in the choice of terminology I have adopted to describe Community products vs Enterprise products in the jboss.org - community driven announcement.
The word 'product' is important here as for many people it is traditionally associated with something that is sold. Likewise the 'productization' process is traditionally seen as the steps that take place in order to convert something into a form where it can be sold, i.e. a product.
The trouble with reserving these words for commercial interests means that there is no simple way to define the deliverable of a community driven software project. You could call it a release but this is missing the point. If the community works together on a JBoss.org project to produce something, then whatever they produce is by definition a product! Support can still be provided by the community but at no charge.
In the commercial world, Red Hat employees work together on an Enterprise project to produce products called Enterprise Platforms or Frameworks.. These are then supported by Red Hat for a subscription fee.
Using the terms project, product and support evenly in this way allows you to see the parallels that exist between the two models without introducing any unnecessary confusion.
The differences between Community products and Enterprise products are:
Community products - based on individual projects, configured for development, fast release cycle, supported by the community.
Enterprise products - based on a collection of projects (Platform) or a single project (Framework), configured for production, slow release cycle, supported by Red Hat.
Over the coming days and weeks these guidelines will help to shape the development of content for the individual projects as we embark on the next stage of JBoss.org.
The goal is to deliver content in a way that is easy to consume and that allows Community products to be used productively.
