[pmwiki-users] Concept, Task and Reference

[Bellave Jayaram]

I have been slowly adding content to the PmWiki site by adapting the core
principles of DITA. Although I don't yet have a gentle introduction to DITA
for PmWiki authors, I will try to explain things as I go along. 

 

Basically, DITA advocates hierarchy of information types and specialization
as required. At the highest level of information type, we have "topic".
Under "topic" there are 3 different types of "topics" - For ex., I have
created these pages in the PmWiki group on pmwiki.org as follows:

 

Concept - this is a kind of glossary except that it is very generic in
nature and thus it is common to all audiences

Task - this is a chunk of information that relates to a task in the PmWiki
context

Reference - this is a chunk of information that refers to another chunk of
content in the PmWiki context

 

Inside Concept, each (concept) entry has beginning and ending anchors. For
ex., within [[#releaseDirS]] and [[#releaseDirE]] anchors is the release
directory structure. Wherever needed, one can access this chunk of
information by using: 

 

(:include Concept# releaseDirS# releaseDirE:)

 

Programmers are used to this sort of chunking but it is not always intuitive
to non-programmers. Anyway, the idea is 'define once, use multiple times'.

 

A similar kind of thing can be done inside the Task and Reference pages.

 

I have created a Test.Installation (since I did not want to mess up the
PmWiki.Installation page) page that shows how the nested includes work
(unfortunately, it is not pulling in the release files chunk from the
Concept page since I forgot to put PmWiki.Concept in the lower level
include).

 

I won't get into specialization just yet but there are several advantages to
this type of organization. By adding audience markup and by creating trails
(see my page Profiles.BJayaram for what I am thinking), we can create useful
"lessons" for various tasks for readers, authors and admins.

 

I welcome everyone's feedback on this.

 

Jayaram

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: /pipermail/pmwiki-users/attachments/20060317/d43f7633/attachment.html