Difference between revisions of "Introduction to Modular Documentation"
From Joomla! Documentation
(New page: 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, onli...) |
m |
||
| Line 5: | Line 5: | ||
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. | 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. | ||
| − | + | {{Chunk:Chunk}} | |
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. | 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. | ||
Revision as of 12:51, 11 May 2008
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.