Wiki-based Documentation for Logistics Software
The goal of the project was to develop a concept for end-user documentation for customer-specific software that manages business and logistics processes. The documentation was to be written in an existing company wiki based on MediaWiki.
Approach and methods
To ensure a consistent structure of wiki articles, to enable users to quickly find relevant content, and to provide an authoring workflow, the wiki contents had to be enriched by semantic meta information. For this purpose, we installed Semantic MediaWiki (http://semantic-mediawiki.org/) and customized functionalities and metadata according to the following project requirements:
- Custom forms enable users to create and edit wiki articles that are structured by content classes according to the DITA standard (see http://dita.xml.org/standard): task descriptions, reference information, and conceptual information.
- The forms harmonize both the structure and the layout of wiki articles, making it possible to create/edit articles without having a deep knowledge of the wiki syntax.
- Special metadata provides the basis for automatically-generated navigation elements such as multi-level tables of content, browse buttons, and index pages. These search and access functions supplement the standard full-text search capabilities that all wikis provide.
- Custom queries automatically generate links to related topics at the end of each article.
In the course of the project, we defined company-specific terminology and authoring guidelines, which we documented in a wiki article. Special wiki pages for wiki authors and editors make it possible to filter wiki articles according to their workflow status and to manage index keywords.
Last but not least, we collaborated with the logistics experts to identify and document the most important tasks that users of the logistics software face, such as calculating shipments, creating export documents, generating invoices, and so forth. The documentation provides wiki articles for these topics:
- Each task is described in a task-oriented wiki article (task topic).
- Each task topic is linked to relevant reference topics that describe the software windows/dialogs that are used during the task.
- Each task topic is linked to relevant concept topics that describe the underlying rules that apply to the task, for example, for calculating invoices.
- Each software dialog provides context-sensitive linking to relevant reference topics in the wiki which enables users to directly jump to the right topic when they click the Help button.
Insights
About Fr. Meyer's Sohn (GmbH & Co.)
Fr. Meyer’s Sohn (FMS) is a family-owned global forwarding company. It is one of the 10 largest sea freight forwarding companies worldwide. Tailored customer solutions across all modes of transport are also part of its product portfolio, as is the optimization of supply chains.