Category Archives: open standards
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
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?
- 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.
- 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.
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.
- 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:
- Alan J. Porter – Writer, speaker, consultant
- Anne Gentle – Technical writer for OpenStack
- Ellen Feaheny – CEO of AppFusions
- Mark Fidelman – Social business GM at harmon.ie
- Robert Rhyne Armstrong – Director of documentation for RouteMatch Inc
- Sherif Mansour – Technical product manager at Atlassian
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:
- Log in as a Confluence system administrator.
- Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
- Type “scroll wiki docbook exporter” into the search box and click “Search”.
- Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
- 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.
- 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.
- Click “Tools” > “Export to DocBook”.
- Adjust the options in the dialog that pops up:
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:
And here is an extract of the DocBook XML:
<?xml version=”1.0″ encoding=”UTF-8″?>
<book xmlns=”http://docbook.org/ns/docbook” xmlns:xlink=”http://www.w3.org/1999/xlink” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd” version=”5.0″ xml:id=”scroll-bookmark-1″>
<title>Confluence, Tech Comm, Chocolate</title>
<title>Confluence, Tech Comm, Chocolate</title>
<title>A wiki as platform extraordinaire for technical communication</title>
<para>By Sarah Maddox</para>
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!
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:
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:
- Choose “Browse” > “Confluence Admin” > “Plugins” > “Install“.
- Type the name of the plugin (“Scroll Wiki EPUB Exporter”) into the search box and click “Search“.
- Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
- 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 (email@example.com) asking for an evaluation licence. When it arrived, I installed the licence key onto my site. Here’s how:
- Choose “Browse” > “Confluence Admin“.
- Click “License” under “Scroll Wiki EPUB Exporter” at the bottom of the left-hand navigation panel.
- Paste the licence key into the text box.
- 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:
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“.
And voila, it’s as easy as that. Here’s another picture of the Bitbucket documentation open 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!
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.