Mozilla Popcorn Maker and a tour of the Confluence documentation

Mozilla’s Popcorn Maker is pretty neat. You can grab a video and augment it with clickable text boxes. You can also add other interactive widgets, such as a live Twitter stream or a fully-functioning map from Google Maps. I’ve been playing with Popcorn Maker for a couple of weeks, and I thought other people may like to have a go. So I’ve put together a video for you to mess up… hrrm… review. It’s cunningly disguised as a tour of the Atlassian Confluence documentation. But actually, it’s a bit of fun. ;)

Popcorn Maker is all online. There’s nothing to download. You give it the URL of a video from YouTube or another supported location, then drag and drop events onto the video. The Popcorn Maker editing environment adds a timeline, a bit like the one you see in a Flash editor, but driven entirely by Javascript, HTML, and CSS. You also get a library of widgets to add and configure, such as text boxes, popups, maps, Twitter streams, and so on.

Jumping right in

Are you keen to try Popcorn Maker? Try making a remix of my Popcorn Maker movie, “Popping the Confluence docs“. I’d love it if you’d add a comment on this blog post with a link to your remix!

Making the video itself

I used Screencast-O-Matic to record the movie itself. It’s a great tool too. Just like Popcorn Maker, everything is online. You do need to install Java on your computer, and it’s handy to have a webcam for the audio part of the movie. Other than that, all you need is your connection to the Internet. You can use Screencast-O-Matic free of charge, if you’re happy to have a watermark at the bottom of your movie.

Once I’d made the movie, I uploaded it to YouTube and then used Popcorn Maker to annotate it and make it available for remixing.

Some thoughts on Popcorn Maker

It’s pretty cool to be able to grab a video from YouTube (or Vimeo, Soundcloud, or an HTML 5 video) and add bits to it online, all within your web browser. Nifty technology!

But I think the huge potential lies in the fact that anyone can remix the videos. Just grab a movie that someone else has created, and decorate it yourself.

This has very interesting possibilities for collaborative development of “how to” videos. Another use that springs to mind: The review of videos. Instead of writing separate notes, people can paste their comments directly onto the relevant spot in the video. And they don’t need specialised tools to do it.

The icons and styling in general could do with some tender loving care from an artist or designer.

The integration with Twitter, Flickr and Google Maps is awesome! It makes me wonder what other integrations would be useful. Perhaps a HipChat room. Or an RSS feed from WordPress?

I’d also love to see some way of finding and sharing remixes of a given video. Ha ha, searching for “Popcorn remixes” brings up a number of song remixes!

References

• A Mozilla blog post introducing the Popcorn Maker technology: Introducing Popcorn Maker
• The main Popcorn Maker site: https://popcorn.webmaker.org/
• A Popcorn Maker tutorial
• An article from PCWorld: New Mozilla tool lets anyone create and hack interactive videos
• An article from Co.Design: Popcorn Maker: A Dead-Simple Drag-and-Drop App For Remixing Web Videos
• A list of Popcorn Maker projects
• Screencast-O-Matic, an online tool for recording screencasts: http://www.screencast-o-matic.com/
• The video on YouTube, without the Popcorn Maker annotations: Confluence Documentation Tour
• “Popping the Confluence docs” – a Popcorn Maker movie for you to remix to your heart’s content. :)

STC Summit day 2 – Using DITA

I’m at STC 2012, the annual conference of the Society for Technical Communication. This post contains my notes from a session called “Using DITA”, by Michael Priestley, lead DITA architect at IBM.

Michael started off by telling us what DITA is and giving us some historical background.

What is DITA and who is using it?

DITA (Darwin Information Typing Architecture) is an open standard for designing, creating and publishing modular information, such as technical publications, help sets and websites. The standard is owned by OASIS. It was originally created for technical communication, but was designed to be more broadly applicable. We are starting to see other types of content adopt the DITA standard now too, such as learning and training. As a result, some LMS systems are now adapting to support DITA too.

The latest DITA standard, OASIS DITA 1.2, was approved in December 2010.

A public survey at ditawriter.com conducted a survey and found that around 250 companies have posted public case studies. Breaking the usage down by industry sector, around 30% of companies that use DITA are in the software sector. Geographically, the largest number of DITA users is in North America, followed by Europe.

In technical communication, a survey in 2008 found that DITA was the most popular standard, at 35%.

Michael discussed some case studies from around 2008-9,including the reasons why the companies adopted DITA :

• Avaya adopted DITA to solve problems of low-quality for globalised content, inconsistency in content and style, and problems in training new writers. They reported improvements in these areas, as well as increased user satisfaction and happier writers,
• CaridianBCT adopted DITA to reduce translation costs. They reported savings of $100,000 in the first year.
• Medtronic needed to improve productivity. The metrics quoted were based on the amount of content that the team managed to produce using the new reuse model.
• WebSphere adopted DITA for content reuse in the documentation for their application server product. They report 80% reuse of their content across the entire set. Note that the percentage of reuse required depends on the amount of commonality across the different products.

Smart content

Michael discussed a study by the Gilbane Group, called “Smart Content in the Enterprise”. One of the most interesting aspects was a shift from an inward-facing to an outward-facing view of the content. Focus on what the users need from the content, and on delivery as the starting point of design.

The core elements are providing metadata, integrating social systems with the content, and using structured content as the source.

Getting practical – DITA topics and maps

DITA is all about chunks of content called topics. This concept has nothing to do with reuse. It’s all about content use. With all types of content other than novels, people jump in and out of a book or manual to find what they need. They don’t read the book from start to finish. What we must do is understand what the user needs to do, and prioritise that over the needs of the product.

Here Michael took us through the core elements of DITA:

• The high-level structure of a topic in DITA.
• An example of a DITA map. A map does all the referencing and organising. You would have a map per output format.
• A map in topic links.
• A map with generated navigation and links. The build process takes the information in the map, and turns it into a table of contents and supported linking patterns.

Conditional processing

Michael showed us the underlying DITA tags for conditional processing. We don’t assert that you should include or exclude something. Instead, we assert that it applies to a specific product or products.

Then you set conditions as part of the build process, to include or exclude products, or to flag specific content.

Conref

In some cases, you want to reuse a fragment of a topic or a fragment of a map. In those cases, you would use a conref.

A conref is basically an empty element that instructs the build process to pull in the content from another element at publication time.

Note that you should do this as little as possible. In most cases, you would use conditional processing to include or exclude a topic. Reason: If people change a paragraph, it could mess up your content reuse. Topics are a more basic unit of structure, and so are less subject to breaking changes.

Information typing

The idea is that different types of information are best served by different structures. What’s more if a particular type of information is presented in a particular structure, that will help the user understand the information.

DITA defines a specific set of structures for tasks. For example

• Prerequisites
• Steps
• Warnings

Each of the above elements has sub-elements, and rules about what can go where. The task  is a type of topic. You can use a task anywhere that you would use a topic. The task has rules unique to it. We call this “specialisation”.

What’s new in DITA 1.2?

• Taxonomies. Michael showed us the big vision of how his team uses taxonomies to provide progressive disclosure from the product UI to the web-based user assistance.
• Learning and training specialisations.

What’s coming in DITA1.3?

The group is working to provide a lighter-weight DITA editing experience, for technical communicators and other DITA users too.

Michael’s presentation style is easy and authoritative. Thank you Michael for an informative insight into DITA.

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.

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:

• 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:

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:

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:

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:

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:

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“.

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:

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!