Hello World

2012-06-05

Lillian Kirsten McCance

On June 1st, Silke and I welcomed into the world our new baby girl, Lillian Kirsten McCance. We’re very happy (and very tired) new parents. View more photos.

It has again been decided that April 27th will be passive voice day. Fun will be had by everybody as the passive voice is used for tweets, blogs, and casual conversation. The active voice will be frowned upon. The hashtag #passivevoiceday should be used when passive voice is used in social media, so the fun can be shared by all.

Why is this being done? Simple. It’s considered fun. No point is being made. It’s just enjoyed when things are taken to an absurd extreme.

It is hoped we will be joined by you, and that the word will be spread to everybody known.

I’m happy to announce that I’ll be hosting the Open Help Conference & Sprints again this year. Last year was a great success, with attendees from projects like Mozilla, GNOME, FreeBSD, and Ubuntu, as well as people from the commercial tech comm world.

The conference features two days of presentations and open discussions, sort of a mix between a traditional conference and an unconference. We talk about everything that has anything to do with open source or community-based documentation, including tools, techniques, style, localization, and accessibility. If it helps us help more users, we’ll talk about it.

After the conference, we have three days of multiple team sprints, with impromptu cross-team discussion. As a GNOME person, it was extremely interesting for me to see the Mozilla team in action last year. We do a lot of things differently, and it’s great to colocate our sprints so we can learn from each other.

We’re looking for interesting presentation proposals. See the Sessions page if you’d like to present. We’ll also have a tools showcase: a set of lightning talks where we all show off the awesome tools we make and use.

I’m really looking forward to seeing everybody again, and to meeting more interesting people.

Open Help Conference & Sprints

Hey! Why not add that banner to your own site or blog to help us spread the word?

API Docs on Mobile

2012-03-20

I’ve blogged before about mobile-friendly Mallard output. The HTML created by Yelp’s universal XSLT automatically adapts to small screen sizes in a number of ways, such as reducing extra borders and padding, dropping the number of columns used for certain link groups, and making links thumb-friendly. None of this is surprising to seasoned web developers, but for some reason we still don’t see a lot of it in technical communications and single-source publishing.

There’s a whole lot we can just do automatically when working with a working with a structured source format like Mallard or DocBook or DITA. Some things we can’t do without knowing the author’s intent, like removing non-essential screenshots. And for that, I’ve blogged before about using Mallard Conditionals to exclude images from mobile.

But what about those pesky code blocks? For decades, old farts have fought to keep lines of code under 80 characters. On common phones now, even 80 characters is too wide. You have more like 30 or 40 before you have to scroll horizontally.

Automatically reformatting code is probably outside the scope of good sense, but when API synopses are created dynamically, as with the API Mallard extension I’ve worked on, we can adjust the rendering fairly easily. Here’s a synopsis in a typical desktop browser:
API synopsis at 684px wide

And here’s the same synopsis with the line breaks and indentation dynamically adjusted for a mobile device through CSS:
API synopsis at 321px wide

Obviously, we can’t do much about a function name that’s just too long. But it’s fairly easy to make a synopsis which is at least somewhat readable on my phone. All of this is built into the tools and requires no extra work from authors.

Mallard Cheat Sheet

2012-01-29

Mallard cheat sheet:

When trying to run ‘make distcheck’ on gnome-user-docs, I got this error:

make[1]: execvp: /bin/sh: Argument list too long

This roughly translates to “You have so much documentation translated into so many languages that your poor build system can’t handle it.” Congratulations to everybody involved in reaching this wonderful error.

Update: I’ve added a custom distdir target to yelp.m4 to fix this problem. If you maintain a package with a large document and a lot of translations (gnome-user-docs, ubuntu-docs), install yelp-tools 3.3.2 before making your next release. You may need to run ‘make distclean’ and rebuild completely to get the new build rules.

 

Last time, I gave a demo of a Mallard document rendered in a way that adapts to handheld devices like phones. Because Mallard is not a presentational language, most of the formatting can be adjusted automatically, and authors don’t have to worry about anything. But sometimes, you really do want to change the content when viewing on a handheld device.

First, though, let’s look at some specific formatting differences between desktop and mobile. For each of the pages below, click the ‘Desktop’ and ‘Mobile’ links above the iframe to see the difference.

  • Desktop Help – The purely decorative hover previews are turned off for mobile. (Good luck hovering with your finger anyway.) Also, the three-column grid changes to a two-column grid.
  • Delete files and folders – The notes and step lists use all the available horizontal space. The automatic links at the bottom fill the whole page width as well.
  • Sound, video & pictures – The two-column link layout changes to a single column, and the link boxes span the entire page width, making them easier to tap.

But sometimes we add content that’s visually helpful on large screens, but cumbersome at small sizes. Things like screenshots are often nice to have, as long as they don’t get in the way. This is where conditional processing comes into play. I’ve been busy retooling Mallard conditional processing to allow things like this:

<media src="figures/shell-top-bar.png" if:test="!target:mobile"/>

The result is an image that’s only displayed in non-mobile reading environments. Switch between desktop and mobile on these pages to see it in action:

This isn’t limited to images, of course. You can use conditional processing on any block element or list item. What’s more, Mallard conditional processing allows full branching and fallback, giving you an easy way to display one thing for the desktop, and something else for mobile.

Don’t want to read? Skip to the Mobile Mallard demo.

As people use more and more mobile devices, it’s important that we can deliver help in a way that feels comfortable to users. It’s not just about help for mobile apps. Look at any book on documentation from the 80s or 90s and you’ll see an example about a field technician using documentation differently than an office worker. But now people are increasingy using phones and tablets to read documentation for everything, including devices in the world around them.

Mallard is already a natural choice for creating help to deliver on mobile platforms. Its focus on small, focused topics and its decidedly non-book-like navigation structure fit comfortably on a small screen, and its minimalist structured markup means you can easily adapt it to new needs without carrying a bunch of legacy baggage.

But the design we use for large, mouse-driven screens don’t always feel right on small, finger-driven devices. We use multi-column links that feel scrunched on small screens. We have purely decorative link previews on hover that you can’t even get to with your finger. We have margins and padding that are refreshing on large displays, but they just keep you from seeing more content on your phone. Luckily, Mallard doesn’t specify these kinds of presentation details, so we can make help that adapts to the form factor you’re viewing it on.

Check out the Mobile Mallard demo to see the initial work on making Mallard documents more suitable for mobile devices. This is still very early work, and it needs a lot of real-world testing. The next step is to use Mallard conditional processing to allow you to actually control what content is shown on mobile devices.

Know stuff about databases and SQL? Then we could use your help on the Knowledgebase for MariaDB. MariaDB is a community-developed fork of the popular MySQL database (now owned by Oracle). A top-notch database deserves top-notch documentation, and a community project needs contributors like you and me.

Getting involved is easy. Just create an account or log in with your existing OpenID account. Then pick a page and start editing. And don’t forget to keep in touch. Join the #maria channel on Freenode, and join the Maria Docs group and mailing list on Launchpad. Don’t forget to introduce yourself!

We’re working on getting a public TODO list online to make it easier to contribute. Until then, here’s a short list of things you can help with:

  • CREATE TABLE
    • Add a section about PRIMARY KEY. Include a brief description of what it does. Provide a reference for both the PRIMARY KEY keyword on a single column and defining multi-column keys.
    • Add a section about FOREIGN KEY and REFERENCES. Include a brief description of what it does. Provide a reference for both the REFERENCES keyword on a single column and defining multi-column foreign keys.
    • Add a section about INDEX, including SPATIAL and FULLTEXT. (Should these have separate sections? It depends on how full the sections get.) It’s probably worth putting all the detailed information about indexes on the CREATE INDEX page and just link there from CREATE TABLE and ALTER TABLE.
    • Create a section describing TEMPORARY tables.
    • Write documentation for the various table options and the partition options. Some of these require more in-depth experience using MariaDB or MySQL.
  • CREATE EVENT
    • Explain the various SCHEDULE options thoroughly, possibly with examples.
    • Explain the time units.
    • Explain the ON COMPLETION, ENABLE, and DISABLE keywords.
  • CREATE DATABASE
    • Write documentation about CHARACTER SET and COLLATE.

This is just a sampling of a few easy places to get involved. I have more; ping me (shaunm) on IRC. Or leave a comment here.

Mallard and EPUB

2011-11-10

Did you know you can easily convert a Mallard document into an EPUB file? It’s built right into Yelp Tools, the collection of documentation tools built on top of the core of the Yelp help viewer. Install yelp-tools from your package manager and run the following command in a directory containing Mallard page files:

yelp-build epub .

If you have Yelp customization stylesheets you use for the web, you can use them for your EPUB output too. Or you can create customizations to better fit the form factor of an e-book reader. Of course, as with everything from Yelp, the formatting is non-ugly by default.

Don’t forget that a Mallard document is just a collection of pages that link among themselves dynamically. If you want to publish an EPUB of only certain pages (for example, to provide your accessibility topics for people to read from another device), just limit it to only the pages you want. There’s no need to hand-edit a driver file.