Wiki documentation – Splunk on MediaWiki
This week I had the privilege of being given an expert guided tour through a technical documentation site running on MediaWiki. It’s a very cool site. These are the notes I wrote up after the session. I hope you find them useful! It was very interesting for me to have such a detailed look at documentation running on a wiki other than Confluence.
Rachel Perkins walked us through the Splunk product documentation, running on a customised MediaWiki platform. She and the rest of the Splunk documentation team have designed customisations to support their requirements. As well as the tools visible to the general reader on the documentation site, Rachel has added tools that make life easier for the authors on the wiki. In particular, authors can define the product manuals, tables of contents and product versions in text files, with metadata associated with each manual and version. Writers can also branch and inherit documents when a change is required for a specific product release.
Here are a few of the things that struck me about the site, even before Rachel walked us through it:
- splunk>docs: What a cool name!
- A very solid, comprehensive documentation site.
- Left-hand navigation bar showing table of contents.
- Feedback form at the bottom of each page, asking “Was this documentation topic useful?“
- Navigation at the bottom of each page, pointing to the start of a section and the next topic.
- PDF export option available on every page.
- Tool at the top allowing you to select the product version and manual that you want.
- Some user comments on the pages, but not very many. (Rachel later explained that they would like to encourage more comments. She wonders if the blue line at the bottom of the page discourages readers from scrolling further down.)
- A separate wiki for general discussion and community input.
- A section called “Hot Wiki Topics” at the top left of the wiki pages.
Rachel explained that the primary goal in selecting MediaWiki as their platform was to make the documentation as collaborative as possible. This platform made that easy. It is also important that there is a lively community of developers.
The authors value the “live” aspect of the wiki. The content is immediately available, as soon as you save it. At first, authors were a little disconcerted that there was no lengthy publication process. Rachel estimated that it took about two months for them to get over their apprehension. The advantages are that readers always have the latest information, and writers can fix problems at any time. Rachel monitors all updates via RSS feeds, which are a standard feature of MediaWiki.
- PDF exports. All manuals are available as PDF files. Customers can generate them on the fly, for the entire manual. The way it works is that the tool caches the PDF file and serves it up to each reader. It only regenerates the PDF file if there has been a change to the content. This functionality is provided by an open source plugin that Splunk has customised. PDF versions of the manuals are very popular.
- Documentation structure. Splunk have added wiki customisations to support the division of documentation into manuals, chapters and pages. To create the structure, writers edit a text file. One text file defines the list of manuals shown in the dropdown list at the top of the screen. Another text file defines the table of contents of each manual. If you load that page in view mode, you can click through from the table of contents to each page. If the page does not exist, then the tool creates a new shell page and populates it with template content.
- Versions. Similarly, there is a text file to define the versions of the product. Each version has metadata that defines its status, such as
- Branching and inheritance. What is branching? Let’s assume you need to change a page because the functionality it describes has changed in the latest release. You would then branch the page, so that you leave one branch documenting the earlier version of the product and another branch for the new version. One page can apply to many versions. You can branch a page, a set of pages, a manual or the entire documentation suite. Splunk have created a tool called the “Branch and Inheritance Console”, where you choose the version you are branching from and to, choose the manual or pages that you want to branch, and then complete a number of selection fields to create the branch. There is no awareness of the content itself. So, for example, if you change the content of an earlier version, you may need to apply the same change to the later versions too, and you would have to do that manually. Note that a page may or may not need changing for a particular version. Note from Sarah: This is very neat! Permission control (via MediaWiki’s access groups) is by version. The general public will only see the newest version when you change its status to
released. Everyone can see the versions numbers across the top of the page, indicating which version(s) the page applies to. This means that all contributors know which version to edit.
- Context-sensitive online help. This is another wiki customisation, done via tags (labels) on the pages. Each page can have any number of tags, and those tags form a kind of unique help ID for the page. Rachel recommends a minimum of three tags to ensure a unique combination. There is a file that maps the tags and product version on the page to the link from the application screen. This means that writers can move and rename documentation pages without changing the help links in the product. If a help link points to a non-existent mapping, it goes to a default page.
- Search. The search backend is a wiki customisation. They use the Google Mini Search Appliance. Rachel wants to improve aspects of the search, for example it does not recognise word stems. It’s pretty neat, though. It returns results for the version that you are currently in, or for the latest version if none is specified. Splunk uses the same backend for all its sites, not just the documentation. This means that you see search results from various sites, such as the documentation and the wiki, all on one search results page. A very nice feature is the “Search tips” panel that appears at the top of the search results sometimes. Rachel’s team have written a paragraph of tips that matches certain search terms, and will appear in the panel if someone searches for a matching term. People really like this, Rachel says.
- Feedback form. There is a feedback form at the bottom of each page, asking “Was this documentation topic useful?” The resulting feedback is mailed directly to the documentation team. Each team member responds if they have something useful to say. They love getting this feedback. The tool does not use any external service to collect the feedback. Rachel is not sure whether it is part of MediaWiki or a plugin.
- Left-hand navigation bar. This is a customisation, not a standard part of MediaWiki.
- New version of the platform. Rachel and the team are working on a 2.0 version of the platform. It will support multiple products (currently it only supports one) and will have a new look and feel.
Rachel mentioned that she is very happy with the documentation platform. I am very impressed too.
Splunk is in the process of making the customisations (all except the search) available as an open source project, headed up by Taylor Dondich. The open source project, not yet publicly available, has a working name of “Ponydocs“. Cute!
Thank you so much for a great walkthrough, Rachel! And congratulations to the Splunk team for this excellent set of documentation.
Posted on 18 June 2011, in open standards, technical writing, wiki and tagged MediaWiki, online help, plugin, technical communication, technical documentation, technical writing, wiki. Bookmark the permalink. 3 Comments.