Category Archives: open standards

STC Summit day 1 – Getting started with HTML5

I’m attending STC 2012, the annual conference of the Society for Technical Communication. Monday afternoon started with a presentation by Peter Lubbers, called “The future is landing: Getting started with HTML5″.

Peter’s presentation covered these points:

  • HTML5 – what and why
  • HTML5 features
  • Toolkit

The world is moving to HTML5. Peter thinks the impact on the world will be even bigger than what DITA has been to tech comm.

HTML5 will not replace DITA. We will probably continue to author in DITA. The two are complementary, especially with respect to the semantic markup.

What is HTML5?

  • HTML5 is the new major milestone for HTML. It includes things that have earlier been separate specifications, such as JavaScript APIs.
  • The focus is very much on webapps, and creating webapps that are on a par with desktop applications. One of the components that eventually merged into the HTL5 spec was originally called Web App 1.0.
  • It represents an explosion of growth in many different areas.

Why should we care?

  • New features that “pave the cow path”. For example, new features in web forms.
  • A simplified Doctype. Just “HTML”.
  • Simplified character set in the meta tag.
  • Simplified markup. You can create a minimal document in just 70 characters! The browser will supply the fill-in elements.
  • HTML5 is universal, works in all world languages, and is designed for accessibility- semantic markup and WebVTT (format (Web Video Text Tracks) is a format intended for marking up external text track resources).
  • You need fewer plugins.
  • HTML5 is designed to be secure.

Next Peter took us through the new HTML5 elements. The new tags are semantic – making a first class element out of attributes that people commonly used, such as a figcaption element for image captions. One of the benefits of semantic markup is making the document machine readable.

Some elements gave also been declared obsolete, such as frames, framesets and inline styling.

Peter recommends the HTML5 Doctor site.

There is a lot of new functionality around web forms. For example, in a signup form you can specificy a “placeholder” attribute containing text that appears in an input field before the user has entered anything. (It typically appears in grey text, and disappears as soon as you click in the field.) You can also add an attribute that makes a field mandatory. Field types are useful for specifying dates, colour pickers, and so on.

CSS3 is part of HTML5, and defines a number of new features, such as rounded corners, transitions, web fonts.

Media queries are very important, especially when you talk about responsive web design. See the website The Boston Globe as an example. You can drag the browser window, and change its size, and it remains looking good. You can define the way the page should look, and the columns that should appear, based on the width and height of the window.

In the area of audio and video, HTML5 supports a number of media formats and gives you a simple way of including them. There are some hiccoughs with browser supports and codecs, but basically it works.

Peter recommends the Miro video converter for converting movie files to different formats for browser compatibility.

For graphics and 3D figures, Peter talked about two types of graphics API:

  • Canvas – HTML5 has a “canvas” element. You can think of it as a programmable bitmap, where you have complete control over every pixel.
  • SVG. Not new, but HTML5 now has native support for scalable graphics. One of the great libraries for SVG is D3, an open source project that you can roll into your own projects.

For a cool experience on an iPhone, try the Kaazing racer. The car responds to changes in the position and orientation of the phone. This is based on the device specification in HTML5, and also on the new web sockets technology.

One feature that will affect technical communication is the ability to make documents available offline. If you add the necessary elements to your HTML, the browser will cache the pages and make them available offline, at the same URL.

Toolkit:

  • Authoring tools, such as MadCap Flare, support HTML5.
  • Modern browsers support many of the features. See the HTML5 test page to check the overall compabitility ofour browser. And see When can I use… to check specific HTML features. For mobile browsers, see Mobile HTML5.
  • PageSpeed is a great tool for analysing the speed of your page and telling you what to do to fix the performance. It’s an add-on that you need to install.
  • For getting started, Peter recommends HTML5 Boilerplate, which includes a complete set of templates for a web page. It includes years of learning about best practices.
  • Modernizr gives you a library of feature support detection. It will pull in extra code for browsers that do not support the feature. Also HTML5 Cross Browser Polyfills.
  • There are also a number of mobile emulators that help you develop HTML5 pages for mobile devices.

Above are the notes that I took during Peter’s presentation. There was a lot more that I didn’t have time to capture. Peter has posted his slides on SlideShare. Thank you to Peter for a very interesting presentation, full of useful tips.

Writing a book with DocBook and a Confluence wiki

We’re in the final stages before sending my book off to the printers. Exciting! While we wait, let me tell you a bit about how the publishing team and I have produced the book. We’re using a Confluence wiki and DocBook XML.

Cover of "Confluence, Tech Comm, Chocolate"Here’s our process in brief:

  • Plan, write and review the book on a Confluence site.
  • Use the Scroll Wiki DocBook Exporter to convert the content to DocBook XML.
  • Use DocBook XSL-FO style sheets to create a PDF file for sending to the printers.
  • Use XSL to generate ebook formats too.

This post is about writing and reviewing the book on the wiki, and converting the Confluence content to DocBook XML – the first two points in the list above. Richard Hamilton, at XML Press, is the expert on the further DocBook processing.

A bit about the book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. Details are at XML Press. It is all about developing technical documentation on a wiki, with a focus on Confluence wiki. And just to be ultra meta, I’ve written the book on a Confluence site. Dogfooding FTW!

Writing, planning and technical review on the wiki

Richard Hamilton and I have spent the last nine months on a Confluence wiki site. We kicked off our planning there in May 2011. Since then, I’ve spent around 400 hours writing the content on the wiki. Ryan Maddox, our illustrator, has uploaded his images onto the wiki. For two weeks in early December, the technical reviewers joined us there too – six knowledgeable and enthusiastic people:

The wiki was abuzz with review comments, opinions and counter-opinions, laughter and chat.

Now it’s gone a bit quiet while Richard and I work on the last stages of book production. When we launch the book, we’ll open up the wiki site too. You’ll be able to join us there and make it buzz again. 🙂

DocBook for the publication processes

DocBook is an XML standard for documents, developed by O’Reilly as a means of making their publishing process more efficient. It is now an open standard maintained by OASIS.  Richard Hamilton, at XML Press, uses DocBook XML to publish a range of books on the subject of technical communication. Using a customised set of the open source XSL style sheets for DocBook,  Richard can create HTML, PDF (through XSL-FO), EPUB and other epublishing formats from the DocBook source.

Converting content from Confluence wiki to DocBook XML

So, I’ve finished writing the book and the reviewers have worked their magic too. It’s all on a Confluence wiki. The content is stored in the Confluence database in wiki format. How do we get it to DocBook so that Richard can create the print and ebook formats?

Enter the Scroll Wiki DocBook Exporter.

Scroll Wiki DocBook Exporter is a plugin for Confluence, developed by K15t Software. (A plugin is a small piece of software that extends the functionality of the wiki. It is similar to an add-on for a web browser.) Once you have installed the Scroll Wiki DocBook Exporter on your Confluence site, you can export a page, a set of pages or an entire space, to DocBook XML.

How to use the Scroll Wiki DocBook Exporter

The first thing is to add the plugin to your Confluence site. You need to be a Confluence system administrator, then you can install the plugin in the usual way:

  1. Log in as a Confluence system administrator.
  2. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
  3. Type “scroll wiki docbook exporter” into the search box and click “Search”.
  4. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
  5. Click “Install Now”.

See the Confluence documentation on installing plugins.

You will need a license key from K15t Software. They provide a free evaluation license that gives you full functionality for 30 days.

Once the plugin is installed, a new option appears in the Confluence “Tools” menu, allowing you to export the content to DocBook format.

  1. Go to the page that you want to export. If you want to export a set of pages, go to the parent page of the set.
  2. Click “Tools” > “Export to DocBook”.
  3. Adjust the options in the dialog that pops up:
DocBook Exporter dialog

Scroll Wiki DocBook Exporter

When you are ready, click “Start Export”. The plugin will create a zipped file containing the DocBook XML and attachments, and will offer the file to you for downloading.

A sample of the output

Here is one of the book’s pages on the wiki:

Book's front page on the wiki

Front page of the book on the wiki

And here is an extract of the DocBook XML:

<?xml version=”1.0″ encoding=”UTF-8″?>
<book xmlns=”http://docbook.org/ns/docbook&#8221; xmlns:xlink=”http://www.w3.org/1999/xlink&#8221; xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance&#8221; xsi:schemaLocation=”http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd&#8221; version=”5.0″ xml:id=”scroll-bookmark-1″>
<info>
<title>Confluence, Tech Comm, Chocolate</title>
</info>
<part xml:id=”scroll-bookmark-2″>
<title>Confluence, Tech Comm, Chocolate</title>
<chapter xml:id=”scroll-bookmark-3″>
<title>A wiki as platform extraordinaire for technical communication</title>
<para>By Sarah Maddox</para>
</chapter>
</part>

[SNIP]

<index />
</book>

Index, footnotes and figure captions

The Scroll Wiki DocBook Exporter supports these too. The plugin adds a number of macros to Confluence, which you can use to mark up the index entries, footnotes and figure captions. I’ll write another post with the details. I’m sure many people are agog to know how this works. 😉

Working with K15t Software and XML Press

Richard and I have worked on this project with Tobias Anstett and the rest of the team K15t Software.  They are great people to work with: knowledgeable, enthusiastic and energetic. As far as I know, this is the first time anyone has written a book on Confluence for publication via DocBook XML. We have added new functionality to the plugin, especially for the index and footnotes, adapting and tuning as we go.

Thank you all. It’s exciting to help perfect a plugin that many other authors and technical writers will be able to use.

And I can’t wait to get my hands on a copy of the book!

Publishing documentation to ebooks from Confluence wiki

I’ve been having such fun over the last couple of days, playing with the Scroll Wiki EPUB Exporter. It is a plugin (add-on) for Confluence that converts wiki pages to EPUB format. What amazed me was how easy it is to create ebooks this way, and how very shiny they look on an iPad. A definite “ooh” moment.

The Scroll Wiki EPUB Exporter exports Confluence pages to an EPUB file. EPUB is an open ebook (electronic book) format developed and maintained by the International Digital Publishing Forum. EPUB supports reflowable content, meaning that the content’s layout changes to suit the device on which the content is being read. HTML is another example of a reflowable format. A growing number of devices support the EPUB format, including the iPhone, iPad, Android devices and a number of ebook readers and tablets.

I used the Scroll Wiki EPUB Exporter to convert the Bitbucket user’s guide from Confluence wiki to EPUB format. Then I pulled the EPUB file into the iBooks app on the iPad. Here’s what it looks like in iBooks:

Publishing documentation to ebooks from Confluence wiki

I’m a technical writer, so now I’ll show you how to do it. 🙂

Installing the EPUB exporter plugin

First I installed the EPUB plugin onto my test Confluence site. In case you’d like to try it out too, here’s a quick guide to installing a plugin into Confluence. You need Confluence system administrator permissions to do this:

  1. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install“.
  2. Type the name of the plugin (“Scroll Wiki EPUB Exporter”) into the search box and click “Search“.
  3. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
  4. Click “Install Now“.

Alternatively, download the plugin (it’s a JAR file) from the Atlassian Plugin Exchange and save it on your computer. Then go to the Confluence plugin installation page, as described above, and click “Upload Plugin” to upload and install the plugin JAR file manually.

Next I emailed the team at K15t Software (sales@k15t.com) asking for an evaluation licence. When it arrived, I installed the licence key onto my site. Here’s how:

  1. Choose “Browse” > “Confluence Admin“.
  2. Click “License” under “Scroll Wiki EPUB Exporter” at the bottom of the left-hand navigation panel.
  3. Paste the licence key into the text box.
  4. Click “Save“.

Ready to epublish!

Converting Confluence pages to EPUB

Once the Scroll Wiki EPUB Exporter is installed, there’s a new option in the Confluence “Tools” menu: “Export to EPUB“. Click it to see the export screen:

Publishing documentation to ebooks from Confluence wiki

Scroll Wiki EPUB Exporter options

The plugin produces a zipped file with a .epub extension. Next, I wanted to see the document on an ebook reader of some sort. There’s an iPad in the house, so let’s try that.

To get the file onto my iPad, I emailed the file to myself (well, actually to Peter, because the iPad is his). I opened the email message on the iPad, tapped the attached file and tapped “Open in iBooks“.

Publishing documentation to ebooks from Confluence wiki

Opening an EPUB file from email on the iPad

And voila, it’s as easy as that. Here’s another picture of the Bitbucket documentation open in iBooks on the iPad:

Publishing documentation to ebooks from Confluence wiki

Bitbucket documentation in iBooks on the iPad

iBooks is a built-in app (application) on Apple’s iPad 2. It is also available for download from the App Store.

Two things came to mind

While writing this post, two things struck me.

Firstly, I wanted to take a screencast so that I could post a video showing the page turning and other cool aspects of iBooks. There’s no way to make a screencast on the iPad! I would have had to make a video using a camera.

Secondly, I started thinking about the content itself. It’s great that we can now make ebooks so easily. Technically, the problem is solved. Write the content in Confluence then export it to EPUB and people can read it on all sorts of devices.

But we need to think about the actual content. People using ebooks will not necessarily want to click links that point to websites and the infamous “more information”. They may not even want a practical “how to” guide. In the case of the Bitbucket guide in particular, people on ebook readers probably will not be able to write any code or access their source repository to try out the steps. Instead, perhaps the content destined for an ebook should be more of an overview, introductory or inspirational nature.

Love the EPUB exporter plugin

The Scroll Wiki EPUB Exporter is in beta release at the moment. I’m sure the developers would love any feedback we want to give. Anyone can write a review on the plugin page. Congrats to the guys at K15t Software – consider my hat doffed!

Social web documentation strategies – notes from Anne Gentle’s webinar

Early, very early, this morning I attended a webinar run by TCANZ, with Anne Gentle as the guest speaker. The webinar was titled “Social Web Documentation Strategies” and was based on Anne’s STC Summit 2010 presentation. I really enjoyed hearing Anne speak in person! Here are the notes I took from the session. Any mistakes are mine, and all the credit goes to Anne. 🙂

Anne started off discussing the fact that it can be risky to introduce social strategies into your organisation. To help reduce the risks, she suggests these 3 steps:

  1. Listen first. See what’s out there and get the feel of the existing communities.
  2. Find your role. In the presentation, Anne discussed a number of the roles applicable to documentation on the social web.
  3. Align your content strategies with business goals. Everyone brings certain expectations to websites, and they bring different levels of expectation to different types of content.

Listening

Anne points out that technical writers are very good at this. We are technically skilled and we know a lot about our products. She suggested some tools:

  • Google Alerts. You can do really precise searches. For example, you can search only blogs, and pick up content about only your product. You could view your entire customer database as a community, and get insight into the things they are talking about. Anne works on a project called OpenStack, with Rackspace. She finds that bloggers are a very good community to start a conversation with.
  • Technorati offers a blog-only search. This is neat because it includes a filter based on authority, taking into account how often the content is linked to, how many influential people link to it, and so on.
  • Delicious and tagging. If you know who in your community may be tagging, this is a good way of finding out who is talking about what.

This is all part of the listening phase. Don’t jump in and start talking too soon. Don’t automate your tweets or posts. Don’t automatically follow people. Do identify yourself and the company you work for. At Rackspace, where Anne works, the social media policy is “be helpful when you are online”. Anne also recommends that we should be conversational: let it flow and be natural.

Anne talked about checking the “social weather”. She compared it to checking out the atmosphere in a restaurant. Is it quiet and romantic, or crowded and noisy? In the same way, online communities have different atmospheres and conventions.

Another useful technique is “sentiment ratings”. You can do them in Twitter Search (advanced search) . More heavy-weight tools are Radian6 and others. This technique gives you an idea of whether customers are happy with a tool, or more likely to hate it. Radian6 was recently acquired by SalesForce. The tools are becoming more advanced. See what clues there are on the social web to get a good picture of what our customers feel about our product.

Social technographics is the art of finding out how likely people are to take part in social web activities. Are they like to write a blog, tag something in Delicious, post tweets, and so on? The tools analyse the demographics and help you decide whether people in your target audience are likely to actively create content or take part in your activity, or are more likely just to read. This helps you to choose the social activities you want to initiate.

At this point I lost my Internet connection and was offline for ten minutes or so. When I got back online, Anne had moved on to talking about roles.

Finding your role

Anne is now talking about roles, I may have missed a few due to being offline. This is where I came back in:

  • Reporter/observer role. This is someone who has good listening skills, and spends time finding out who is writing the really good stuff.
  • Enabler role. A good tool is DISQUS, that provides a widget at the bottom of each page where people can comment. You can see threaded conversations, moderate the comments, even migrate comments from one page to another. The role of enabler is one that Anne fulfills. She gave an example of seeing a comment about a particular tool on the documentation, and how she was able to connect the customer with the developer of the tool.
  • Sharing role. Provide tools on your site that people can use to share your pages via Twitter, Facebook, and so on. For example, a tool called TweetMeme adds a retweet button to a page.
  • Syndicating your content, so that people can subscribe to it. You can offer people notifications about updates to content, and you can embed content from RSS feeds onto your own pages. Anne showed us an example of a side panel she has added to a page, showing a feed from a particular blogger who was writing content relevant to her documentation.
  • Collaborator/instigator role, telling people what content needs writing. This works really well in an agile development environment, where you are actively asking people to write the content. You need a content platform where everyone can edit the documentation. In the open source development environment, collaboration is actually a technical requirement. If this makes sense in your business, you would go to the “final frontier” and provide this type of community documentation. You need to align this with your business goals.

Aligning your content strategy with business goals

Anne gave a list of business goals that align themselves really well with a social documentation strategy.

  • The need to track a campaign or the effectiveness of your content.
  • Creating customer experience of collaboration and community.
  • Helping people to help each other: peer to peer support.
  • Decreasing the response times on support requests.
  • Generating ideas. People in a community bring lots of ideas. If they are willing to share and contribute these ideas, you can crowd-source ideas.
  • Rewarding contributors by offering them special experiences. Even rewards that are not monetary are valued, such as badges and other types of recognition.

The way we do business is evolving. We want these social customer insights. No matter where you are in the business, whether in marketing or other areas, there are use cases for using social tools and the social web for meeting these goals. Social CRM is gaining traction. The famous use case is Heather Armstrong who runs a blog called Dooce.com. One day her dryer broke when her baby was only a few days old. She couldn’t get it fixed. Repair men came and went, but nothing worked. So she started tweeting about it. That’s exactly what the dryer manufacturer does not want. They want her to tweet rather about how positive the relationship was. Anne says that the onus is on the business to meet the customers where they are.

Starting your own community

Before jumping, you need to realise that there are communities out there already. For example, forums, Twitter chats, a popular blog. Before building your own community, find out if there is actually one already that you can collaborate with.

For example, the Mozilla Developer Network is becoming a bit of a hub about Google Chrome too. Anne thinks this is really great. They could have started their own community. Instead, they joined an existing one.

Pitfalls. Anne mentioned a number. Here are just a few.

  • Too much content, without enough opportunity to take part and become engaged.
  • High barriers to entry.
  • Should you run a pilot, a sort of trial with a limited audience? One problem is that people may not believe that you are fully committed if you do a pilot. You need to analyse your community. In some cases, a pilot may indeed be helpful.

Next Anne ran through the benefits of measuring the participation and engagement in your community. You need to set up some KPIs. These are a few of the measurement points that Anne mentioned:

  • New versus returning visitors. Do you want a high number of new visitors, or is it more important that people keep coming back?
  • Time on site: You may want people to spend a lot of time, or maybe the fact that they found the answer and left is good.
  • Search results. Did people find what they were looking for?
  • Download rates. Did people find and download the content they needed?
  • Do people add comments, and are your support staff answering them?

After doing all this analysis, then you can make the decision about whether it makes sense for your business, to apply a social media strategy.

Then you launch and learn.

At this point Anne called out to me and said that I’ve been an inspiration to her. Wow, thank you Anne. The same is so true in reverse.

Managing community content

Next Anne gave a number of pointers about managing community content. For example, you must be able to accept content that is not 100% perfect. You need to help people build a relationship with content. They’re not likely to build a relationship with text only. A good tip is to add a profile picture of yourself.

Anne showed the example of Adobe Community Help. It is all searchable, including the comments and user-generated content. Anne was looking for some information, and found the answer in a comment from a technical writer who said she couldn’t put it in the official documentation because it was more in the way of a workaround for the way the product worked. This is a great way of getting help.

Anne ran through a couple more examples: Intuit, Mozilla, Ubuntu and OpenStack. The OpenStack project is where Anne works, and she talked with enthusiasm about the great experience she and the team are having in building the social site.

An interesting analysis showed that there are four motivations for people to contribute:

  • I help someone because they will help me.
  • I want to build my reputation.
  • I feel obligated to help, because it’s a great tool that is helping me.
  • I feel like a I belong, because it’s a fun community.

Summing it up

In closing, Anne went back to the point of aligning content with business goals. Which areas of the business are we aiming to support? For example, marketing and sales, service and support, research and development, and so on.

She said that we need to do this. Yes, it’s scary and confusing. But there is a target and there is a goal: Serving customers with our content.

My conclusion

Thank you so much to Anne Gentle and to TCANZ for hosting this webinar. Anne is a great speaker. Her enthusiasm and professionalism both shine through. For me, it was definitely worthwhile being online at 7am!

Black swans

Black swans in autumn

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.

Walkthrough of Splunk documentation on wiki platform - MediaWiki

Splunk docs home page

First impressions

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.

The walkthrough

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.

Walkthrough of Splunk documentation on wiki platform - MediaWiki

A page in the Splunk docs

Features:

  • 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 released and unreleased.
  • 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.
Wiki documentation - Splunk on MediaWiki

Search results showing a custom search tip at the top

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.

%d bloggers like this: