First of all my apologies for the delay in getting this project started. It's been a particularly busy time for us and the template tutorial had to take second place for a while. To move things forward Ian and I have now decided to focus on separate areas, so while Ian will be working with the J!101 people, I will be looking after the new template tutorial.
The Doc Team finds itself in the unusual position of having a significant number of volunteers who have expressed an interest in helping us produce the new template tutorials. Not including Ian and myself we currently have 21 people who have put their names forward. The question arises as to how we will manage such a large team. I've given this considerable thought in the last few days and I think we have an ideal opportunity to try something that I've had in mind since the early part of this year. What I'd like to do with this project is use the technique of "Modular Documentation" to produce modular, re-usable documentation. There is a learning curve here, for me as much as anyone, but I'm pretty certain that this methodology will produce the most useful result in the time available. It also lends itself to a team-working environment where people can take on particular roles that suit their particular interests and skills.
The idea is that we do not write a complete document, such as a tutorial, as a monolithic object. Instead we write small, standalone modules that make sense in any document context and in any reading sequence. A tutorial, for example, can then be constructed by assembling a subset of these modules, adding only formatting and cross-referencing to make the finished document. Importantly, a different subset of the same modules can be assembled into a different document for a different purpose or target audience. This is the essence of re-usability.
So how do we go about writing these modules? Well, each module answers a basic question: who? what? when? where? why? how? As a rule, each module answers one question only. There are several types of answers and each module will answer the question in one way only, although different modules can be constructed to answer the same question in different ways.
Having created the modules, we assemble them into documents in a specific format and for a specific audience. Examples of such documents would be printed manuals, online help and training materials. In order to produce the finished document we do not add anything except cross-referencing which can take the form of tables of contents, inline cross-references and indexes. Apart from the cross-refences all our content takes the form of re-usable modules.
We begin the process by identifying and building "primary" modules. Each primary module will be of one of the following types (listed alphabetically):
- Definition lists These are most commonly used to list components, so for example, we might create a definition list which lists the names of the principal files contained within a template and introduce the purpose of each.
- Glossaries These are a specific form of definition list that defines technical terms.
- Procedures These are step-by-step instructions that explain how to perform tasks.
- Processes These are similar to procedures and topics. Processes differ from procedures in that they are narrative rather than imperative. They explain what someone or something does (declarative), not what users should do (imperative).
- Topics These are texts that answer specific questions.
- Troubleshooting scenarios These are a hybrid of topics and procedures. Each scenario explains one problem and its solution.
Primary modules may themselves contain secondary modules, such as the following:
- Itemised lists
These secondary modules can be constructed separately, although they don't have to be. For example, figures will probably be constructed using a separate graphics package and may well be produced by a graphic artist working independently within the documentation team. Secondary modules can be re-used within different primary modules. Documents are assembled from primary modules only; secondary modules must be integrated into primary modules before they are used.
Much in the spirit of "agile programming" in which Joomla! itself is developed, we will try to practice "agile documentation" so that at any point in time it will be possible to generate an output document and quickly see the state of development of the documentation effort. This can be used to further refine the modules and improve the quality of the end product. How we generate these "builds" is not entirely certain at the moment and we may need to create new tools to support this process, but hey, we have access to some of the smartest developers on the planet so anything is possible.
There has already been some brainstorming going on in this thread: http://forum.joomla.org/index.php/topic,201431.0.html. Let's continue throwing up ideas but in particular let's look at the kinds of modules that we might construct.
And for those that haven't already introduced themselves, please add a little something to this thread: http://forum.joomla.org/index.php/topic,201429.0.html. Oh, I guess that should include me....
Let's get started and have some fun!