MediaWiki: Supporting IMSMA Documentation

by Dionysia Kontotasiou and Olivier Cottray [ Geneva International Centre for Humanitarian Demining ] - view pdf

Over the last few years, wikis have arisen as powerful tools for collaborative documentation on the internet. The Encyclopedia Wikipedia has become a reference, and the power of community editing in a wiki allows people all over the world to contribute their knowledge. Use of a wiki for software documentation provides an effective collaboration tool as information can be easily fed into the system. Certain wiki implementations, such as MediaWiki, are project-oriented and include functionalities such as automatic page versioning, easy navigation, simple search mechanisms, as well as online, offline, and mobile usage.

Software projects tend to generate different types of documentation, ranging from initial user requirements and specifications to user guides and system documentation and the code itself. Code is typically managed within a software framework or code management system. At the Geneva International Centre for Humanitarian Demining (GICHD), the Atlassian Jira bug-tracker is used for issue tracking in the Information Managment System for Mine Action (IMSMA) project.1,2 Formal (paper) documents such as specifications and user guides would typically be stored in a product lifecycle management (PLM) or document management system (DMS), but these are not suitable for administrator and user guides’ documentation. To fill the gap, a centrally supported wiki for software project documentation was requested by the information management (IM) team in the IMSMA documentation project in 2013.

Figure 1. Portals
All figure courtesy of GICHD.
Figure 1. Portals
All figure courtesy of GICHD.
Figure 2. Navigation boxes
Figure 2. Navigation boxes.
Figure 3. HowTos.
Figure 3. HowTos.
Figure 4. Sidebar.
Figure 4. Sidebar.
Figure 5. Page tabs.
Figure 5. Page tabs.

Methodology

This article addresses the use of MediaWiki to support IMSMA documentation at GICHD, reports on the current state of the IMSMA documentation, and describes what has been achieved since 2013. The requirements for the development of IMSMA Wiki are laid out in Section 1 to show why we chose an approach based on MediaWiki.3 Section 2 introduces the basic features of the IMSMA Wiki and how a user can navigate them while reading IMSMA information. In Section 3, analytics (internal and external) are presented to showcase IMSMA Wiki’s impact, and in Section 4 we address the different challenges of using MediaWiki as the documentation tool for IMSMA.

Requirements Elicitation and Identification (Section 1)

During the requirements elicitation stage, the first step is to identify the stakeholders, i.e., the persons or groups of persons who have interest in the produced software documentation. The stakeholders have specific needs that they expect the documentation to meet. Understanding the stakeholders and the ways they intend to use the documentation is essential as this helps to determine the forms of future documentation.

After identifying the stakeholders, the next step in the process is to identify the requirements. First, the requirements coming from stakeholders were gathered. The identified requirements had to be carefully addressed in order to ensure that the produced documentation can be properly used for the intended purpose as well as maintained and, if necessary, extended in the future. The second step in identifying requirements for IMSMA documentation was the analysis of existing documentation.

Evaluation Against Identified Requirements

In this section, we review every requirement in order to understand whether the produced documentation has fulfilled the identified requirements and, if not, the reason for that discrepancy.

Figure 5. Page tabs.

Figure 6. IMSMA Wiki in ZIM format opened in Kiwix reader. The latest version of IMSMA Wiki’s ZIM file can be downloaded at http://mwiki.gichd.org/IM/Downloads.

Using IMSMA Wiki (Section 2)

Anyone can access the IMSMA Wiki at http://mwiki.gichd.org. Its basic features are as follows:

Figure 7. IMSMA Wiki page opened in mobile view.

Figure 7. IMSMA Wiki page opened in mobile view.

Navigation. Every page on the IMSMA Wiki has information to show and allows users to move to other pages. This is called navigation. To help users navigate, there are several navigation elements:

Searching. For searching, we use the core MediaWiki installation. The quickest way to find information in IMSMA Wiki is to look it up directly.

On every page there is a search box. The user should enter key words and phrases and press Enter or click the magnifying glass icon or the Search button. If a page has the same title as what the user entered, the user jumps straight to that page. Otherwise, it searches all pages on the wiki, and presents a list of articles that matched the user’s search terms, or a message appears informing the user that no page has all the key words and phrases. If the user clicks the Search button without filling in anything, he/she will be taken to Special:Search, which gives extra searching options (also available from any search results list).12

Tracking Changes. MediaWiki offers a collection of special pages and tools to keep track of what is going on in the IMSMA Wiki. For example, IMSMA Wiki users can track recent changes to all pages (http://mwiki.gichd.org/IM/Special:RecentChanges).

The most interesting page is Special:RecentChanges.13 This page displays all edits, file uploads, page moves, deletions, and other actions done in the IMSMA Wiki. The menu at the top offers a collection of links to customize users’ displays, i.e., limit the number of changes or the number of days shown, or restrict the display to show edits to a certain namespace only.

Glossary. This is a glossary of terms commonly used in IMSMA Wiki and is accessible at http://mwiki.gichd.org/IM/Glossary.

Offline Usage. Kiwix is an offline reader for web content.14 GICHD uses it to make IMSMA Wiki available offline. This is done by reading the content of the documentation stored in a file format ZIM, a high compressed open format with additional metadata.15

Mobile Usage. By default, MediaWiki does not offer mobile device-specific support, making MediaWiki sites difficult to use on mobile devices. This has been mitigated in many ways by the MobileFrontend extension, which provides a mobile-friendly view of IMSMA Wiki.16

Figure 8. Page and edit statistics covering the period December 2013 to March 2017.

Figure 8. Page and edit statistics covering the period December 2013 to March 2017.

IMSMA Wiki Statistics (Section 3)

Internal Statistics. MediaWiki offers an internal analysis of various metrics like page creation and edits. However, these metrics do not reveal much about the traffic.

Google Analytics

Google Analytics Integration Extension has been installed to track IMSMA Wiki traffic.17

Several filters were created in Google Analytics to block and remove the irrelevant traffic (i.e., crawlers, bots, and spams), and include the following:

  1. Creating a Valid Hostname filter for Ghost Spam. This filter includes only the valid hostnames (in our case, mwiki.gichd.org). This kills the ghost-referral spammers (traffic that comes from other hostnames).
  2. Creating a filter for Crawler Spam. This second filter excludes known spammer domains from this list.18
  3. Creating a filter for Fake Languages and other Spam Types. This is the latest form of spam in Analytics. This well-known spammer uses the language HTTP header to send messages as languages and uses legitimate sites like Reddit, Twitter, motherboard.vice.com or TNW (The Next Web). The hostname filter will prevent most of it; however, there are a few hits that may sneak in, a kind of mix of crawler and ghost spam. A third filter was added to exclude language spams.
  4. Creating a filter for Page Title Spam. This is a combination of ghost and crawler spam.
  5. Creating a filter for Screen Resolution exclusion. Automated bots have no screen, so the screen resolution almost always equals “not set.”;
  6. Enabling “Exclude all hits from known bots and spiders.” This is a bit easier because Google Analytics has a built-in feature to exclude this traffic. It is using the IAB’s “International Spiders & Bots List” for this, which is updated monthly.19
Figure 9. Google Analytics with (all users) and without (all users – clean) irrelevant traffic covering the period December 2013 to March 2017.

Figure 9. Google Analytics with (all users) and without (all users – clean) irrelevant traffic covering the period December 2013 to March 2017.

Challenges (Section 4)
User Involvement. Because of the collaborative nature of wikis, and the desire to use them as tools of information transfer, all group members need to be actively engaged in the use of the IMSMA Wiki as an information resource and in the editing of the IMSMA Wiki content. One necessary component of any wiki development is that its use be pushed by one of the primary maintainers, someone who will encourage use and development of articles and content, and will actively patrol and motivate new users. The wiki thrives through use, but a single person or group of individuals who support the growth and encourage new users to learn how to use the wiki and its many functions must drive use initially.

To better promote user involvement and engagement, we use the Contribution Scores extension, which polls the wiki database to locate contributors with the highest contribution volume.20 The extension is intended to add a fun metric for contributors to see how much they are helping out.

Protection. Wikis are designed to be open documents and to make entry and editing of information easy. Making it difficult to edit pages is counter to the spirit of the collaborative effort, and detrimental to success of the project. However, there are many cases to be made for page protection in the event of information that should not change, complex page structure that could easily be damaged, and user control of certain information. These cases are limited, and typically handled by granting the user, in control of that particular page, advanced privileges.

To overcome this protection challenge, we use the restrict access by category and group extension.21 Even though Mediawiki is a free/public access collaborative document tool, sometimes it can be helpful to have a restricted view of wiki documents.

Multilingual Support. There are two main use cases for language support across IMSMA Wiki: the language of the content and the language of the interface.

Conclusions
For larger projects that generate lots of documentation, it is essential to enforce some structure to keep information in the right place. As with any website or information system, there should be someone in charge of maintaining project documentation and ensuring that the contributed information
is valid.

Use of wikis for project documentation greatly facilitates communication and learning from project contributors. A true wiki implementation allows authenticated users to edit and add information and corrections to every page. Thanks to the open approach and simplicity of use, wiki usage grows organically without the need for training sessions or system coaching like for PLM systems. In particular, for projects spanning multiple organizations in several countries, an easy-to-update shared documentation and communication medium on the internet can be of great value. c


Biography

Dionysia Kontotasiou
Information Management Division
Geneva International Centre for Humanitarian Demining

Dionysia Kontotasiou Dionysia Kontotasiou joined GICHD in March 2013 as a MediaWiki specialist. She is the technical manager of the Information Management System for Mine Action (IMSMA) and administrator of the in-house MediaWiki website that serves as IMSMA’s documentation and support site. Prior to joining GICHD, she was a research assistant in the Informatics and Telematics Institute in Thessaloniki, Greece. Kontotasiou earned a diploma in Electrical and Computer Engineering and an MSc in Medical Informatics from Aristotle University of Thessaloniki.

Olivier Cottray
Information Management Division
Geneva International Centre for Humanitarian Demining

Olivier CottrayOlivier Cottray joined GICHD in January 2012, initially as the information-services coordinator. As head of the Information Management Division, he is in charge of managing the team that provides information-management capacity development and technical support to the mine action community. Prior to joining GICHD, Cottray ran geographic information systems (GIS) support cells in the U.N. and nongovernmental field operations and helped found the NGO, Map Action, and has run emergency GIS cells in a number of countries. Cottray earned a Bachelor of Science in geography and economics at the London School of Economics (U.K.), and a master’s degree in GIS and remote sensing at the University of Cambridge (U.K.).

Endnotes

  1. Atlassian. Accessed 5 May 2017. http://bit.ly/JYWkL8.
  2. “Information Management System for Mine Action.” GICHD. Accessed 5 May 2017. http://bit.ly/2qAtrxV.
  3. “Welcome to MediaWiki.org.” MidiaWiki. Accessed 5 May 2017. http://bit.ly/2edEanE.
  4. PHP: Hypertext Preprocessor. Accessed 8 May 2017 https://secure.php.net/.
  5. Portal: Using IMSMA.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2pIHjFc.
  6. “Portal: IMSMA Administration.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2p4N2Xd.
  7. “Portal: Remote Entry.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2pOx5RZ.
  8. “Portal: Business Intelligence.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2pdT5nk.
  9. “Portal: GIS.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2pOi3O3.
  10. “Portal: Technical Notes.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2pdPmGF.
  11. “Portal: Training.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2pOl8xC.
  12. “Search.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2pO8nTM.
  13. “Recent Changes.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2qIKGu9.
  14. “Kiwix.” GICHD IMSMA. Accessed 5 May 2017. http://bit.ly/2qM6Jzx.
  15. “Open Zim.” Open Zim. Accessed 5 May 2017. http://bit.ly/2pOoUY2.
  16. “Extension: MobileFrontend.” MediaWiki. Accessed 5 May 2017. http://bit.ly/2qLZQy6.
  17. “Extension: Google Analytics Integration.” MediaWiki. Accessed 5 May 2017. http://bit.ly/2pOcjlF.
  18. “Historical Spam List – Google Analytics.” Ohow.co. Accessed 5 May 2017. http://bit.ly/2pIL7Gr.
  19. IAB. Accessed 5 May 2017. http://bit.ly/2qA0B0K.
  20. “Extension: Contribution Scores.” MediaWiki. Accessed 5 May 2017. http://bit.ly/2phaDQB.
  21. “Extension: Restrict Access by Category and Group.” MediaWiki. Accessed 5 May 2017. http://bit.ly/2pICfjY.
  22. “Template: Languages.” MediaWiki. Accessed 16 May 2017. http://bit.ly/2rlLZi4.