June 2012
By Anja Weinert and Martin E. Brueggemann

Martin E. Brüggemann has studied Information technology and communication science at Potsdam, Berlin and Aachen and has been working as a technical writer since 2001. He has been working with XTREME technologies since 2007 and manages the Wiki system there.


mbrueggemann[at]xtremetec.de
www.xtremetec.de


 


Anja Weinert studied technical writing in Karlsruhe and has been working as a technical writer since 2007. Since her diploma thesis in 2009, she has been working with Wiki technologies in companies and the dynamics related to it. She has been with XTREME technologies since 2011.


aweinert[at]xtremetec.de
www.xtremetec.de

Wiki as a CMS

Can you have technical documentation based on a Wiki and involving successful collaboration between technical writers, service engineers and developers? Such a Wiki has been set up as a process at XTREME technologies. This article enlists the reasons, the pros and cons and describes the impact of this Wiki on existing processes.

Information is considered to be “data that can be interpreted” and knowledge as “objects and models that we consider to be true and useful, since they explain the world in and around us“ [1]. Now knowledge is a very significant production factor, particularly in our sector, the semiconductor industry. The first thought that might come to mind involves patents that reflect the status of research and secure competitive advantages. Costs incurred due to wrong or obsolete information are a consideration only at second glance. A modification in a drawing can change the electrical connection of a module for example, or modified screws require a different torque. Wrong information can lead to material damages or even worse.

In our case, knowledge as a production factor translates into continuous revision of documents and quick distribution of these changes. About two years back, we, at XTREME technologies, Aachen were looking for a search tool for this purpose - one that would support an extensive documentation project optimally from the start. Our requirements were:

  • Implicit knowledge should be made explicit and made available to all colleagues.
  • Documents were to be developed together by several technical writers at different locations.
  • Central data maintenance and simple distribution: Avoid redundant and contradictory data.
  • Speed before layout: In our sector, a short throughput time is more important for new creates and updates rather than a sophisticated layout.
  • Future-proof and extensible: For the case that our requirements should change in the future, the system had to be extensible.

US English was to be the standard language for creating documents, subsequent translation management could therefore be ignored.

What is a tool?

The Duden says a tool stands for “an object built for specific purposes, with the help of which something can be processed or produced”. Tools extend the existing capabilities of a person and thus ensure that work is simplified.

Popular wisdom says: “The correct tool halves the work.”

We evaluated many approaches, which is shown at the end of the article and finally decided on Wiki technology, specifically a BlueSpice MediaWiki [2].

The reasons behind our decision are provided in the following sections.

Wikis – the advantages

For writers, Wikis present a platform to produce and link information collaboratively, quickly and from distributed locations. Information is stored centrally and is accessible from everywhere, changes can be made immediately and by anyone – we will go into this point in more detail later.

This makes it possible to create contents just as fragments in the beginning and then to add to them and restructure them in the course of time. An optimum is reached step by step in spiral form as more and more information becomes available on the product to be described [3]. Information finally becomes knowledge through this process.

Easy to learn …

The headline may result in a “yes, but” reaction from the reader. And we agree: A Wiki is another tool that technical writers must learn, and the training effort can definitely not be neglected.

The fundamental idea and the way Wikis function must be known to work effectively and efficiently with it. Secondly, the basic syntax must be known (“Wikitext”), although WYSIWYG-Editors (What You See Is What You Get) can significantly simplify daily work.

And here comes the expected “but!”: The BlueSpice MediaWiki that we have used is based on the same software that is behind the famous Wikipedia encyclopaedia for instance. Because of this, MediaWikis are established as a standard, and extensive documentation is available on the Internet.

Version control

Some writers are faced with the same problem time and again during day to day work: A long search for a document in the file system. Once it is found no one can be sure that it is really the most current and therefore the valid version. Copies are created even just by sending documents by email, corrections flow into obsolete documents or must be merged manually.

Apart from this irritation, which can be resolved by the central data storage of a Wiki, there is another requirement stemming from quality assurance: It must be possible to track changes at all times as well as to reverse them if required. Exactly these functions are available by default in MediaWiki.

Modularization and reuse

One function of the BlueSpice MediaWiki is particularly suited to working agile with technical documentation [4]: With “transclusion” it is possible to encapsulate data. Defining modules is a one-time centralized activity and these modules can be reused as often as required – ideal for standard texts relevant for norms.

The process is also possible when only the layout is to be specified, but the text remains variable, e.g. in case of security and warning messages. Transclusions allow calling text modules even with parameters, which doesn’t just allow a consistent layout but also reduces the throughput time in writing.

Since we would like to provide a balanced view of our experiences, it is naturally essential to speak of the disadvantages as well.

This is where the catch can be

Yet another tool – the tool palette of our technical writers was already varied at that time. Working with the Microsoft Office packages was a matter of course, Adobe FrameMaker and InDesign were added on for DTP applications, there was Illustrator and Photoshop for graphics. And now also a Wiki?

Such thoughts cannot be dismissed just by a wave of the hand, but we took the step of introducing the Wiki consciously.

Present-day knowledge management requires the support of technical information systems, which lead to additional costs. The spectrum of systems on offer is multi-layered and the effort of implementation is immense, mainly when a system is to be customized to individual needs. Wikis offer a cost-effective and easy to use alternative: being widespread, the training effort is lower than for other tools, for instance, the user interface of a MediaWiki is known to many users due to Wikipedia. Moreover there are no license or development costs for using open source software. We would however like to point out that “Open Source” clearly isn’t the same as “free of cost” even if there are no license costs involved. The costs shift to customizations and maintenance of software, primarily when high availability is to be guaranteed.

As explained at the start, we were looking for a system that offered the possibility of extension later. Our objective is to replace our DTP software gradually by Wiki functions with the help of later extensions, to be able to further reduce license costs and training efforts. Such customization is possible in open source systems such as Wikis. While providing higher quality, the costs are usually lower than those for developing one’s own software or customizing proprietary software [5].

Minimalistic layout

In case of most Wikis, the print output is always a document in “raw layout”, to put it mildly, due to the limited formatting options. Options to export to various file formats or sophisticated print layouts are not available in standard installations.

It is however helpful that the MediaWiki is widespread and extensions are made available by a large developer community. With these extensions, for the BlueSpice MediaWiki that we use, it is possible to achieve individually adapted print layouts that are no less than those from Office products.

The default user interface of a MediaWiki has been kept very simple, but already several skins are pre-installed, from which users can select as per their choice. Other skins can be installed later and personalized. Therefore we can say that a Wiki doesn’t disturb existing processes due to the diverse options for customization; rather these are enriched and extended.

After the implementation

Now, if we compare the pros and cons, we can see that a Wiki fulfils our requirements exactly. It is also clear that the said disadvantages don’t outweigh the advantages, at least in our context of application.

We now touch upon the changes in the workflows that arose with the implementation of the Wikis.

It is good to trust…

Wiki has its limits, in spite of all its advantages. A company must be aware of these before the implementation, so that the benefits can be weighed against the effort. A Wiki project will always be successful, when it is flanked by measures, since the success depends on many influences and their interactions. One important success factor in the implementation is managing the initial scepticism towards the Wiki technology and the related workflows. The ease and speed of acceptance of the technology is directly related to employee awareness about the functioning and advantages of Wiki. Moreover, Wiki must be fixed and embedded in the internal operational processes.

The contents in our BlueSpice MediaWiki range from background information and technical data to operating instructions and manuals.

For various reasons we also had to question whether we preferred an open or closed system. Should it really be possible for all colleagues to change all contents, which corresponds to the philosophy of a Wiki? Or should changes only take place centrally through the documentation division?

We placed great value on the openness and agility of a Wiki and did not want to limit it through restrictions. For instance, we trust our service engineers to know which tool is best-suited for a task and therefore give them the freedom of directly changing this information if required. If something does go wrong sometime, the changes and the error can be reversed at any time with the help of the versioning function.

But we could also not assume that all colleagues can create ANSI conformant warning messages. The same applied to dealing with standard texts relevant for norms and sensitive contents. Here too access should be restricted if possible.

The following figure shows this conflict:

Figure.: Open vs. closed systems

 

Finally we decided on a middle path. Basically, all content remains open and can be changed by anyone who is on the intranet. Contents relevant to standard texts or security are subject to restrictions. Moreover, administrators are required for data maintenance, as in case of any other CMS. This is not about distrusting other users. Rather, administrators organize the data, e.g. through keywords and following formulation patterns.

Full value CMS?

Is a Wiki a true content management system? The answer is “Yes and No”, as the table at the end will show.

The options of modularization, versioning and access control fulfil important criteria of a CMS. Single-source-publishing and translation management are possible only with appropriate extensions.

What is missing is a complete separation of content and layout. The “Wikitext” used in Wikis, although markup text by definition, offers hardly any semantics, as would be the case when using something like DITA XML for example. To this end, help comes in the form of the MediaWiki extension “Semantic MediaWiki” [6].

Summary

We said at the beginning that we were originally looking for a search tool. The consideration was that we would transfer the data collected in Wiki to a content management system and would adapt the layout using DTP software as soon as the content became somewhat stable. However, we developed our MediaWiki into a CMS through the extension “BlueSpice”, which fulfils all our requirements.

The table below summarizes all our criteria and the systems that came into question. It is easy to identify that a Wiki fulfils the criteria very well.

 

File system1

 

Repository1

 

CMS & DTP-Software

 

Wiki

 

Version control

 

 

X

 

X

 

X

 

Translation management

 

 

 

X

 

(X)

 

Change management

 

 

X

 

X

 

X

 

Collaborative working

 

 

X

 

X

 

X

 

Single Source

 

 

 

X

 

 

Sophisticated Layout

 

(X)

 

(X)

 

X

 

(X)

 

Easy to learn

X

 

X

 

 

X

 

Access control

 

X

 

X

 

X

 

X

 

Reuse

 

 

 

X

 

X

 

1 File system and repository with Microsoft Office products and DTP-Software

 

 

X = Function available

(X) = Available with additional software

 

 

Literature and Links referred in the article

[1]    Endres, A. (2003): Die Wissensgesellschaft und ihr Bezug zur Informatik. In: Informatik Spektrum 26, H.3, S. 195–200.

[2]    www.blue-spice.org

[3]    Boehm, B. (1986): A Spiral Model of Software Development and Enhancement. In: ACM SIGSOFT Software Engineering Notes 11, H. 4, S. 14–24.

[4]    Brüggemann, M.; Sieber, T. (2008): Kathedrale und Basar: Lineares contra dynamisches Vorgehensmodell. In: technische kommunikation, H. 6, S. 53–55.

[5]    Raymond, E. S. (2000): The Cathedral and the Bazaar

[6]    http://semantic-mediawiki.org

Page 1 from 1
1
#1 Fer O\'Neil wrote at Tue, Jun 26 answer homepage

I was surprised by the leap from adding Wikis to aid collaboration in technical writing to transferring information to Wikis as a replacement CMS (or KMS). Wikis indeed have a place in technical documentation for the reasons you stated at the beginning of your article but I haven’t heard a lot of discussion about using one as a stand-alone CMS. I would be interested to read more about what you summarize in your table.

#2 M Brueggemann wrote at Fri, Jul 06 answer

@ Fer O'Neill

 

Sure, just drop me an e-mail!