Actions

JDOC talk

Modular documentation/rendered

From Joomla! Documentation

< JDOC talk:Modular documentation

Modular Documentation

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 this context each module (which we shall 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. We can export content from the wiki to produce documents in other formats such as DocBook XML, PDF and CHM.

A 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. Category indexes are automatically generated by the MediaWiki code.

Templates

Wiki templates are wiki pages which can be used in other pages using a technique called transclusion. They reside in their own content namespace to avoid name clashing with regular articles. In order to use such a template, all you have to do is to enclose its name in curly brackets: {{template name}}.

Chunks

A 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).

Categorising a chunk

It is important that all chunks are correctly categorised as it can be difficult to find them again otherwise. This page gives the correct category tags to add to a page to make it a member of a particular category. Each chunk should belong to at least 3 categories; one each from the following category groups:

  1. Chunk types
  2. User experience level
  3. Joomla! Resource Type

We also started to create wiki templates for chunk categorisation to simplify the process.

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.