PmWiki | PmWiki-DITA / PmWiki-DITA

This is an effort to investigate how to leverage DITA concepts to make this site (pmwiki.org) better organized (in a topic oriented way) and easier to find information for all audiences (author, reader or admin) and at a detail level of basic, intermediate or advanced.

DITA, is the Darwin Information Typing Architecture (DITA). DITA is an XML-based, end-to-end architecture for authoring, producing, and delivering technical information. This architecture consists of a set of design principles for creating "information-typed" modules at a topic level and for using that content in delivery modes such as online help and product support portals on the Web.

Q. Why DITA? Even though PmWiki is not XML-based, what does DITA have to do with PmWiki?

A. In order to fully understand the strengths and weaknesses of DITA, it is necessary to provide a lot of background material. In order to answer the second part of the question, too, we need some familiarity with DITA and SGML concepts. What we will attempt to do here is to limit ourselves to two "architecture" aspects of DITA.

Topic orientation. The highest standard structure in DITA is the topic. Any higher structure than a topic is usually part of the processing context for a topic, such as a print-organizing structure or the helpset-like navigation for a set of topics. Also, topics have no internal hierarchical nesting; for internal organization, they rely on sections that define or directly support the topic.
Reuse. A principal goal for DITA has been to reduce the practice of copying content from one place to another as a way of reusing content. Reuse within DITA occurs on two levels:

Topic reuse. Because of the non-nesting structure of topics, a topic can be reused in any topic-like context. Information designers know that when they reuse a topic in a new information model, the architecture will process it consistently in its new context.
Content reuse. DITA provides each element with a conref attribute that can point to any other equivalent element in the same or any other topic. This referencing mechanism starts with a base element, thus assuring that a fail-safe structure is always part of the calling topic (the topic that contains the element with the conref attribute). The new content is always functionally equivalent to the element that it replaces.

The above answer is still not satisfactory since it contains terminology such as element, conref etc. Ignoring the terminology for the moment, the first attempt we will make is to structure content on this site into topics and use simple PmWiki markup and page includes and nested includes and trails to organize the content.

The next step will be to investigate if additional features of PmWiki can be mapped to DITA so that it becomes possible to select a collection of pages and create a DITA file which can then be processed by other DITA tools.

Finally, if it is possible to set up templates that have design patterns built in for creating new PmWiki documentation, it will be possible to save a lot of time in creating documentation. This last requires things such as topic pull, and map pull etc. which may either take too much trouble to realize or may make sense and be possible. Some brainstorming is required here.

Since PmWiki mixes content and layout, it is incompatible with the DITA way of thinking where the emphasis is on separation of content and presentation. However, just as there is the PublishPDF plugin for PmWiki, there is no reason why a PublishDITA plugin could not be written. Also, PmWiki allows writing additional markup in order to approximate things like ditamaps, XSLT processing etc. The benefit that we have in using PmWiki is that a lot of the XSLT type of processing will not be required as presentation aspects will already be part of the content.

There are two approaches that could be taken. The first approach puts all concepts, tasks and references in three big files which are manually (meaning via include markup entered by a person with no automation or processing by the PmWiki engine to make the markup conform to any map) brought together into a single page or trail containing the content. The concept of hierarchical DITA elements is ignored in this approach.

In the second approach, a group is treated as a DITA element. Thus, PmWiki-DITA would be the top most element, topic (Actually, some pages under that would be of infotype topic and others will consist of what would normally be produced by DITA processing which is content pulled in from the other PmWiki-DITA groups.) Normally, under the topic element we would have the PmWiki-Concept, PmWiki-Task, PmWiki-Reference groups but since PmWiki does not have hierarchical groups, they will be at the same URL hierarchy and considered as being under the topic element by convention. Thus, there would be groups PmWiki-Concept, PmWiki-Task, PmWiki-Reference each of which would be topicref elements. Pages under each would thus be of infotype concept, task and reference respectively.

More to come......

Concept