JDOC:Joomla! 1.5 Template Tutorials Project/Introduction

Communications Channels

In order to help us out you need to be "tuned in" to our communications channels. These are listed below. Click on the link for instructions on how to get connected to each.

• Internet Relay Chat (IRC)

Modular Documentation

The Template Tutorials Project is our first foray into single-source modular documentation and since this technique is likely to be new to most people some explanation is needed here.

The idea behind modular documentation is very simple: we develop content in re-usable modules that can be assembled into finished documents in different formats such as web tutorials, online help systems and printed manuals. We will create a database of re-usable modules in this wiki so that we have a single source from which we can derive documents for different audiences and different purposes.

The key to modular documentation is modular writing. That is, each module is written as an independent, context-free element. In the context of this project each module (which we will often refer to as a "chunk") is a single wiki page.

The process of building a modular document is cyclical. We generate output documents from the source chunks and having seen what they look like we then modify the source chunks until we achieve the desired results. Since we are using the MediaWiki transclusion mechanism, document assembly is effectively instant and so this cyclical process can be very rapid. The output documents can currently be seen on the wiki Main Page. We can also export content from the wiki to produce documents in other formats such as DocBook XML, PDF and CHM.

Each chunk is a small, focussed, stand-alone piece of content that is written so that it makes sense even when taken out of context. Each chunk can be thought of as answering a basic question (who?, what?, where?, when?, why?, how?) and we categorise the chunks according to the type of answer we are giving (for example, a topic, procedure, definition, figure or table).

As more and more chunks are created it becomes increasingly important to have some means of finding them again. To assist this process each chunk is "categorised", meaning that several tags describing its content are added to it. Indexes to chunks by category are available on Joomla! 1.5 Template Tutorials Project#Content_Categories

Transclusion

From a technical standpoint one of the main reasons that we are using MediaWiki for this project is that it supports modular documentation in a natural way through a mechanism called "transclusion". It is important that contributors to this project understand the basic idea behind transclusion as it is the key to understanding how documents are assembled in the wiki from the database of available source modules.

In MediaWiki a conventional link to another page in the wiki is declared by typing something like this into the editor: [[Template:Example of a transcluded page]]. Such a link is shown below. The "Template:" prefix is used here because this is the default namespace for transcluded pages; something we'll come back to in a minute. The link should appear in blue to indicate that the page being linked to actually exists (it would be red otherwise).

Template:Example of a transcluded page

But if instead of using square brackets, you use curly brackets instead, then instead of seeing a blue link you will see the contents of the page being linked to embedded in this page. For example, the next paragraph is actually located in the page called "Example of a transcluded page", and is being included here because below is a link that looks like this: {{Example of a transcluded page}}.

If the page being linked to using transclusion does not exist then the link will appear in red, just like a normal link. If you click on it you will take to the editor where you can create the page.

Click on the "edit" tab for this page to see how it works.

Now for technical reasons I won't go into here, we don't want the transcluded pages for the template tutorials to be stored in MediaWiki's Template namespace. Instead we want them in the Main namespace and to do this the "Template:" prefix is dropped when creating a normal link and a ":" is prefixed to the page name for a transclusion link. So a conventional link will look like this in the editor:

[[Example of a transcluded page]]

and a transclusion link will look like this:

{{:Example of a transcluded page}}

TO BE CONTINUED

Further Reading

Kurt Ament, Single Sourcing: Building Modular Documentation (2003) William Andrew Publishing, New York, ISBN 0-8155-1491-3. You don't need to buy this book as everything you need to know will be documented on the wiki, but if you are interested in knowing more about single-sourcing and modular documentation then this is the book to read.