Creating online documentation with BlueSpice for MediaWiki – tips and hints

Documentation with wiki engines isn’t an innovation anymore, you will find a lot if you look out for them. Especially software developers themselves seem to have a pioneering role in that segment. A lot of those documentation platforms take advantage of the collaborative character of a wiki and let the community be involve in the project. Public but also intern documentaries are increasingly appreciating the specific wiki structures to implement e. g. online manuals. BlueSpice MediaWiki offers powerful tools to support editors while working with the wiki to create online documentations. Please note that a lot of those tools are already available in BlueSpice free, others are additional and fee-required.

The main difference between similar proprietary systems and the open source system BlueSpice is the flexibility: You only get what you really need and you also only pay for the functionality you ordered. Furthermore, with BlueSpice there is neither a license fee nor a graduation of prices according to the number of users. The authorship grows without causing any further costs. And another very important fact is, that there is no vendor lock-in, which means your data belongs to you and is still available even if you decide to terminate the contract.

But let´s get back to the aspects concerning the content in documentations, which are normally most important for the argumentation during a planning and decision phase. In the following, we present the most important questions when implementing an online documentation and give some answers:

Public vs. internal documentation?

In the first instance, the question arises if you want to publish and administrate your documentation public or for internal use. This influences some of the arguments. Of course, it depends on the field of application because operation manuals and organization manuals e. g. are per definition intern. But if you are going to create product documentation, it is worth a thought to involve your customers and fans to work with you. Public documentations offer the advantage of a valuable community feedback. And committed fans volunteer to help editing the content which is profitable for quantity and quality of the documentation. But be aware of SPAM issues in public documentations (have a look at our blog post concerning Anti-Spam-Extensions). In public, but also internal documentations, you need defined guidelines to build structures, help to find content and tools to keep an overview.

Sometimes in internal documentations other aspects are more important than in public ones. For example, many companies have the need for a LDAP/AD connection, so that users can login via single sign-on and don’t have to look for passwords and user names. BlueSpice offers this service with the package Comfort sign-on.

Also important for internal wikis is the possibility to connect different systems to harmonize their functionalities. For example BlueSpice can be connected with SharePoint or DIAS. If you considered your application purpose carefully, you can combine the benefits of the different systems and experience the advantages of a wiki connected to a document management system.

Ask yourself where your documentation platform should be hosted. Most providers offer different solutions and sometimes also a cloud hosting. BlueSpice, for example, also offers cloud and hosting.

Structures in a manual

A manual requires very hierarchical and rigid structures. Due to this, a table of content is of great importance for readers to find their way through the flood of information. If you want to show the structure of a manual also in your wiki you can use the package BlueSpice Bookmaker. With this package you are able to combine single entries from your wiki to a collection of articles. So you can create “books” and even export them. Every article of one book shows a table of content in the content area of the book it belongs to. Navigate with this clickable table of content from one article to the next or jump from one chapter to another.

Page with chapter navigation
Page with chapter navigation

Use portals to summarize topics and collect the most important wiki articles of a handbook. With portals, you can lead the readers to subtopics or provide a general overview. That is how you can divide an extensive handbook into parts and highlight single pages.

In addition to the separation of articles in terms of content, there is a technical way, too. In MediaWiki and BlueSpice it’s possible to define areas which are called “namespaces”. A prefix shows that an article belongs to a certain namespace e.g. “QM:Documentation requirements”. In This example “QM” means “quality management” and shows that the article “documentation requirements” belongs to the topic of quality management. Namespaces separate the wiki into areas and are used to establish the basis for an authorization and permission structure. At the same time search results can specifically be restricted.

To create consistency and structures in the content itself you can use templates. A well thought template contributes to a comprehensive article and the reader is able to get an overview.

Permission management – who is permitted to do what?

Create user groups and define their rights. These permissions are valid for the whole wiki or you can define them just for single namespaces. So if there is sensitive content you need to protect, or you want to create space for the development department, with help of the rights management you can assure that only defined user groups are able to read, edit, delete or approve in this area.

By the way, in MediaWiki and BlueSpice every important functionality refers to a special right, so you are able to define exactly what user group is assigned with which rights.

Set permissions for groups, users and namespaces
Set permissions for groups, users and namespaces

Creating high quality content – what does it need?

Quality in documentations, handbooks and normal wiki articles is opening up a wide field. This is why we start a special series of articles on this issue in our blog. But let´s start with authors of a manual. Mostly there is just a small number of users creating most of the content. These users are very thankful if they don’t have to use the wiki code to format the content. And that is why an extended visual editor (WYSIWYG) is indispensable.

WYSIWYG editor in BlueSpice for MediaWiki
WYSIWYG editor in BlueSpice MediaWiki

At the latest when you start working with tables. If you have to work with complex tables in the wikicode they may drive you crazy. BlueSpice offers a visual editor, which is already included in the free version. This WYSIWYG editor is based on the very popular Tiny MCE. Besides usual formatting functionalities, you are able to create and format tables. It is also possible to copy and paste simple Excel tables in the editor.

Images and screenshots are an essential component of documentation. Therefore, uploading and inserting should be very easy. This is why BlueSpice, compared to MediaWiki, offers a special dialogue for uploading and inserting images. In the same dialogue you can not only define details like licenses and sources but also alignment, size and links. You don’t have to switch pages and edit the wikicode like in MediaWiki.

If you even want more comfort, you should have a look at the package BlueSpice Paste Image. This package enables you to copy and paste or drag and drop images directly from the explorer (also screenshots, which has been created with the “Print” functionality on your keyboard). This saves time and not only wiki beginners will be very thankful when they are able to edit and design an article much easier and faster.

Drag and drop images into a wiki page
Drag and drop images into a wiki page

Sometimes it is necessary or desired that articles are part of an approval process. You can support editing in teams with workflows. Assigning tasks at a certain date to one or more authors helps to assure structured and collaborative editing. If there exist standard workflows you can save and re-use them. In cases of absence or vacation it is also possible to delegate tasks or approvals to a colleague. At a special page you will get an overview of the status of all existing workflows. In BlueSpice you can furthermore assign a responsible editor, who is responsible for a final control and approval of content and images. The status “accepted”, in turn, generates commitment. Only the status “accepted” marks a version as obligatory which means for example only accepted articles can be exported as PDF. Despite this fact it is still possible for authors to edit a “new” draft and actualize contents. To get the full functionality you need BlueSpice Teamwork.

Organize reviews in a team
Organize reviews in a team

Communication and evaluating quality

To assess quality but also actuality of an article at a first glance readers can have a look at the state bar in a BlueSpice wiki. Here they can see the latest author and the date of recent editing. This gives a hint to the editing as well as to the actuality of the content.

Increasing the quality is one of the main goals of the wiki, especially in documentations. Rating and discussing content by readers can contribute to improve quality over the time. So you will find a commenting functionality on every content page. MediaWiki provides discussion pages, which means that every article has its own discussion page where people can exchange their thoughts and ideas according to the content. Additionally in BlueSpice there is a Shoutbox available where you can post comments, useful hints or feedback. The comment box provides the advantage of a lower entry barrier, because it makes it easier to take part at the discussion than a “real” edit.

To evaluate an article as helpful or qualitatively high, you can use ratings (in BlueSpice Rated Comments). Similar to the well-known Amazon ratings you can award an article with up to five stars. Readers are able to assess the quality of an article at a glance. It is also possible to write a detailed recension or, it depends on the use case, experiences, best practices or feedback. These “comments” can also be marked as helpful. This gives you the possibility to get comprehensive feedback – for example in helpdesk descriptions – and already existing but also new ideas can be rated and developed. And if you love gamification you might think of award the 10 best rated articles or something like that.

Special page with all rated articles
Special page with all rated articles

In manuals and documentations media elements are rare. However videos and screencasts are very often a quite useful method to explain difficult procedures in a simple way. MediaWiki (and BlueSpice) offers various players to embed and play videos that are either uploaded to the wiki or hosted at youtube. A range of good “tutorials” increases the quality of contents.

To encourage communication there are not only discussion pages and comments but also an integrated Blog. Use this BlueSpice blog to post news and let them be discussed by readers. If you link the blog at the front page, there is a much higher awareness and people will see activity and progress in the wiki. It is also possible to start single blogs for different namespaces. Just think of the idea to run a blog for every handbook – authors that are involved can coordinate their actions and keep readers up-to-date. Which parts have been edited, which will be edited, where do they need help and also use it to collect suggestions. Let it grow to a central point of interaction about documentation.

But why should we communicate in a wiki when there is telephone, email and coffee breaks? If you start asking questions in the wiki, discuss issues and document answers, the wiki will become a central point of knowledge. All versions and protocols are open to every employee and they don’t have to switch the medium. Nothing gets lost, everyone knows where to look for answers – this is the vision. Additionally, as a back coupling, when people know where to look for information, more users will be an active part of the wiki which means at least frequency will grow.

Who is using a handbook and why? – Search functionalities in MediaWiki and BlueSpice

Let’s start with a short look at people who are using manuals. Nobody reads a handbook from the beginning to the end. In fact they search and read “on the job” – they just look for information they actually need. And normally they need answers on very specific questions. This is why people seldom rummage, because they are looking for a concrete instruction, number or directive. But how do you find this one sentence you need in a mess of information?

BlueSpice offers different solutions. Some of them are already part of MediaWiki, others are extensions of BlueSpice.

If you already know in which environment you have to look for finding your answers, you will be happy about a well structured navigation. On the left side you can link the most important handbooks. Furthermore, BlueSpice offers an individual focus navigation, which means you can add your personal navigation. Fill it with links, pages, categories or tools you need very often. The focus navigation will be your list of favourites. But also portal pages and chapter navigations, which can be created with BlueSpice [bookmaker], offer a good first step into content for people, who already know where to search.

If you haven’t found what you are looking for, use one of MediaWiki’s classics: “All pages”. All articles are listed alphabetically here. You can also filter this list for special namespaces. If you use “all pages” you might have to search meticulously for a title or its synonym – but often you will find even hidden articles.

Another MediaWiki classic is categories. Like tags, they function as keywords for an article and show how to classify an article. With categories you can also get a cross section of the wiki and its namespaces. On another special page all articles that are assigned to a category, will be listed. For example you could get a list of all articles that are assigned to the category “maintenance”. Watch out at these articles for the special issue you are looking for.

Prerequisite for that kind of searching is, that a diligent employee assigned pages, images and files precisely to one or even more categories.

BlueSpice offers two more features to search for content. One is a wiki search that is able to search with query operators in full text and titles and also file attachments and image file names. While you are typing the search term, the system already proposes results. If there is no result you are looking for, you can use an extended search with facets. Use one or more facets like author, category, file or namespace to limit the search results. For example, you can look for articles from a certain author, if you know who edited the article you are looking for. Or you limit the results according to a certain namespace and so on. Step by step you will get closer to what you are looking for. A preview of the articles with the highlighted search keyword in it will help you to decide what result may fit best. By the way this faceted search and the auto-complete function is already integrated in the free version of BlueSpice.

The Wiki Explorer is a fee-required package. With its functionality you will get an interactive table where all articles are listed alphabetically. Choose different columns to define the criteria you are looking for. In the columns you can define filters for every criteria. For example in the column “size” you can limit the list to articles with more than 750kb. Which means only articles that refer to this criteria will be shown in the list. By the way [wiki explorer] is often used by wiki gardeners to find out which pages still have to be approved. You can filter the list of articles precisely by using several columns and define the criteria.

Filter content with wiki explorer
Filter content with wiki explorer

There is another case, in which people are looking for a detailed report of what has changed in between two versions of an article. What changes have been made in this instruction or directive? BlueSpice offers the possibility to compare any two versions of an article with the package Visual Diff. What’s special about this is, that in comparison to MediaWiki, changes will be highlighted in the text and not in a table of wikicode. Added content will be marked green, deleted content red and so on. That makes it easy for you to find even the slightest change in a large article.

Import and export of data and files

When you start with an online documentation you should rethink, if and how existing material shall be integrated. Define how you want to transfer existing numberings and references and take this opportunity to tidy up and throw out old stuff. Data sheets in word, excel and pdf can be uploaded and linked in the wiki but ask yourself if a transferring into a wiki article is more reasonable. This decision depends on the complexity of contents, images and graphs.

Please keep in mind that during this year we will develop a WebDav protocol, so uploaded files can be presented in a folder structure. Furthermore, as we mentioned in the beginning, it is possible to connect file systems like SharePoint and DIAS.

But let’s get to the export. Handbooks or parts of it are often needed on site as PDF or Word. With Bookmaker you can export single pages or whole books as PDF with a cover in your individual design, a clickable table of content, attached files and prodding to approvals (reviews). It is also possible to export to word or html to reuse content in other systems like a DMS or web-based systems like Typo3.


It can be summarized that BlueSpice is, like other wiki engines, well suitable for documentations and handbooks. BlueSpice’s benefit is it’s Open Source core, which means you will get a software without licenses, no vendor-lock-in and you can choose and add only those packages you really need. In addition to this, we develop individual extensions. And on the other hand BlueSpice offers, like proprietary vendors, solutions that include everything you need to fulfill all the conditions for certain use cases like documentations.

Have a look at the BlueSpice homepage to discover more. And if you think about realizing your documentation or handbooks with a wiki, please contact us. Hallo Welt! Is a very experienced partner and we will be happy to support you.


You Might Also Like

Leave a Reply