The GNOME doc team has been having a doc sprint in sunny Norwich, England. I arrived a day late due to crazy snow in Cincinnati, but the team’s been hard at work all week. As usual, there’ve been plenty of feature requests for Mallard, which I’ve been trying to keep track of. I’ve tried to encourage people to join the Mallard mailing list and to file Mallard enhancement proposals. Kat asked for a feature in yelp-tools to check licenses of Mallard page files. I’ve added a “license” subcommand to yelp-check. This is in git master, and I’ll get docs up on the wiki after the next release.
I also wrote a new tutorial on Mallard conditionals. It’s hosted with the rest of the Mallard tutorials on projectmallard.org, and I hope we can adapt it to a chapter on conditionals in the Mallard book. In other Mallard news, Ryan’s been pushing me to resume my work on my non-XML Mallard markdown, so that might see some work soon.
We had our semi-annual discussion about the state of our developer docs and what we can do to fix them. As usual, a lot of problems were identified and a lot of ideas were tossed around, but we never seem to revamp things quite to the level I’d like. Maybe this time will be different.
Allan Day joined us for a few days. I enjoyed working with him on redesigning Yelp. Hopefully Yelp 3.12 will look more like a modern GNOME 3 app. Aside from the chrome of Yelp, Allan took a crack at designing a splash page for the desktop help that has a bit more visual appeal. I’ve been working on implementing this for the last two days. Everybody loves screenshots:
Following our tradition of naming special page styles after our hackfests, this is currently accomplished with the “norwich” style on links elements, along with some uix:thumbs elements on the target pages. Petr’s been pushing me to get thumbnails out of experimental and into Mallard UI proper. Hopefully I can find time to carry through on this after the hackfest.
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.
Earlier today, I gave my talk, Helpful Help, at the Desktop Summit. Unfortunately, there were technical issues with the projector and the video. So nobody saw my slides, and there’s no recording of my talk. My slides are an image-heavy HTML application, but I’ll work on a PDF export for desktopsummit.org. (I am in the business of document tools, after all.) But since there’s no recording, I thought I’d recap the talk in a blog post.
In his keynote session earlier in the morning, Dirk Hohndel related some of his grief in finding documentation. I spent a couple minutes addressing his points. I asked how many in the audience wrote code for GNOME or KDE, and how many of them are professional programmers. Most were. I then asked how many did any documentation work, and how many were professional technical writers. Unsurprisingly, most documentation contributors are not professionals. I have a book’s worth of thoughts on making great documentation with few or no expert writers, but that’s another talk entirely.
I did make the point that single pain points in documentation can leave a worse impression than in software. People don’t usually spend a lot of time looking at the documentation, so if the one experience they had was negative, they’ll have a bad impression, even if the rest of the documentation is stellar. In software, an overall great experience can help users forget about small pain points.
IMG_2291 by Miles Bannan
I went on to tell people to stop thinking about books. There’s an allure to books. Writers aspire to be published. Entire books feel like an accomplishment. And while I think there are places for books, if you approach your help from the book world view, it seriously limits the kind of innovation you can do.
Instead, I encourage people to think in topics.Topics don’t have to be text topics. They don’t have to be in Mallard or DITA or DocBook 5.2. I have three rules for what makes good topic-oriented help: 1) Each topic is self-contained and contains only the information that’s necessary. 2) Topics can be navigated and found using a model that makes sense to the user. Notably, topics need to be able to appear in multiple places in the navigation. 3) Topics are heavily cross-linked so that users can explore if they want to.
With that, I jumped into various hare-brained ideas on things people could be doing with help. Some of these are things I’m actively exploring. Some of them are things I want to explore. Some of them are things I hope others will pick up. I was not giving people solutions. I was trying to plant seeds in people’s minds so they’ll start exploring new ideas in help.
I talked about inlining help. This is the focus of the GLib/GTK+ help API I’ve been working on. See my recent post to gtk-devel-list for details. The idea is to bring the help into the application. Rather than having the help live in a separate viewer, we can make applications fully aware of their help. Help menus and buttons be dynamically populated. Help can be searched directly within the application. We can do super-tooltips much more superly.
I talked about interactive help. I talked about this last year, and it’s a favorite topic of mine. Applications that have a roughly document-like interface lend themselves to doing the help within the interface itself. And when you do that, you can make the help live, so users can explore your application from within the help, rather than using the help passively. The Inkscape tutorials are a great example of this.
I also talked about image and video help. There’s nothing new about using screenshots, and even screencasts are old-hat by now. But they’re still very passive. I talked about how technologies like HTML5 can empower us to create videos that tightly integrate with the text content and the rest of the help.
I then talked about using games as a learning tool. Games are generally not going to be good for on-demand help. But they can be good for exploratory learning. If you make learning fun, people will do it, especially for applications that people consider important to their life or job. I’m not in the habit of promoting Microsoft, but I pointed out Ribbon Hero 2 as a fantastic learning game. Google it.
In every talk I give, I promise the audience two things: They will see XML markup, and they will see pictures of ducks. Without a projector, nobody saw markup or ducks. So go read some Mallard markup, then look at this duck picture:
I’ve never been more excited to be a GNOME developer. After years of hard work and planning, GNOME 3 was released yesterday. Check out the Introduction to GNOME from our brand-new help to learn all about it.
GNOME 3 shows the innovation that open source communities can bring. Hundreds of developers, designers, writers, testers, and translators worked hard to deliver an amazing new user experience. Among them are the fantastic people who helped create an all-new help system that rivals anything I’ve seen elsewhere. My release notes list Phil Bull, Jim Campbell, Tiffany Antapolski, Natalia Ruz Leiva, Shaun McCance, Paul Frields, Mike Hill, Aline Bessa, Marina Zhurakhinskaya, and Kelly Sinnott. If I missed anyone, I’m really sorry. It’s hard to keep track of so much awesome.
We tossed out the old manual (who reads those?) and started fresh with topic-oriented help, building on the dynamic Mallard language. The results are amazing. The initial release has 214 pages, carefully organized and cross-linked to help you find the information you need quickly and get back to your life. What is a workspace?Select files by pattern.Enter special characters.
Frederic Peters did amazing work on library.gnome.org so all the new help is available online. But remember that all of this is available from the Help application on your GNOME 3 desktop. The help viewer was completely rewritten for GNOME 3, and I think you’ll really like what we’ve done.
By the way, if you want to meet up and learn about GNOME’s fresh approach to help, you should come to the Open Help Conference this June. At least Phil, Jim, and I will be there, and we’ll be joined by documentation teams from other great open source projects.
We’re not done yet.
Help needs to constantly improve and evolve as we learn more about what our users need. The GNOME documentation team is already hard at work on more pages and revisions to existing pages. We’ll be pushing updates to the help weekly. If you want to get involved, subscribe to our mailing list and send an email to gnome-doc-list@gnome.org.
We also welcome drive-by contributions. One of the really nice things about topic-oriented documents with Mallard is that it’s easy to just write up a page about something without worrying about making revisions to an entire book. If you love using GNOME, a great way to contribute is by writing a short page about an awesome time-saving trick. We’ll put these under Tips & Tricks, and users worldwide will learn something cool because of you.
Phil mentioned the future of Desktop Help, but he was sparse on details. Let me fill in the blanks. With Mallard, we worry mostly about structure and content, and we leave the rendering details to Yelp. Sometimes we want to influence the style, and for that we use Mallard’s style hints. But sometimes, just sometimes, for very special pages, we want to inject some pizzazz.
We can do that too. Watch:
This is using some custom style hints and a very small Mallard extension, which falls back gracefully thanks to Mallard’s well-defined rules for extensions and fallback.
This is still a work in progress. And with work continuing into the night at the help hackfest in Toronto, it’s very much in progress.
I’m looking for a few talented hackers/writers to help us work on the developer documentation for the Gnome platform in Toronto March 17-22. We’re already hosting a hackfest for user help, and we’d like to colocate a developer documentation hackfest there. We’ll be focusing on the Platform Overview and the new Developer Demos. Time permitting, we can also put some extra polish into our (already mostly comprehensive) API references.
Here’s the skills we’re looking for:
Familiarity with the Gnome platform. You don’t have to be a Matthias Clasen or an Owen Taylor. In fact, knowing too much can sometimes cause you to overlook what new developers need to know. But you do have to have some experience building applications with Gnome.
Some experience writing XML markup. The Overview and Demos are in Mallard. The API references are done with gtk-doc, often with inline DocBook. You don’t need to be an expert on any of these. If you know XML and are comfortable writing it in a text editor, the details aren’t hard to pick up.
Patience and a willingness to learn. Effective writing is more than just dumping what you know into a text editor. We’ll have experienced technical writers on hand who will help you plan and organize your material.
The documentation team will have a hackfest in Toronto from March 17 to 22. Most of the core contributors are already planning to attend. We’ll finish the desktop help for 3.0 and work on as many application help documents as we can. This could mark the first time in years that we ship a point-oh release with complete documentation.
We’re interested in colocating a developer documentation hackfest. We need to add more content and polish to the new developer demos and finish the Platform Overview for 3.0. Time permitting, we can also review and improve our reference documentation. This can only happen if we have people.
So if you have experience with our developer platform and developer documentation, and would like to spend a week making Gnome a more enticing platform to developers, please email me at shaunm at gnome dot org.
I attended the GNOME developer documentation hackfest in frigid Berlin last week. This was, I think, a very successful hackfest. We came out of it with a concrete plan, a new documentation effort firmly started, and a host of improvements to tools in the pipelines.
The plan: We will have an updated Platform Overview. We will have a large and continually growing set of demo tutorials. We will have conceptual overviews for all libraries and major subsets of libraries. We will have complete API references. And we will have a beautiful new developer.gnome.org that acts as a portal to all this information.
Everybody kicked in to create an initial set of demo tutorials. The initial demos focus on getting you up to speed with one of our platform libraries. Further demos will build on this knowledge and help you dive deeper into what the GNOME platform can offer. The demos are in git.gnome.org/gnome-devel-docs/demos/C. We will do our best to make all demos available in multiple programming languages.
The demos are written in Mallard. This is interesting to me, because it’s pushing Mallard in places where it hasn’t been pushed before. This helps me develop useful features. (As a rule, I do not add language features without real-world use cases.)
Jonh asked for line numbering, so I’ve added that in Yelp using a simple style hint. Chris wondered about starting line numbers, continuations, and line number references. These sorts of features require more than an on/off style hint, and I want to think about them more. I think that, with dynamic pages, we can do better than callout lists. Regardless, any improvements there should be in a Mallard extension.
Everybody wanted syntax highlighting. Fortunately, Mallard allows you to provide the MIME type of the content of code blocks, so we already have a way of declaring what should be parsed and highlighted. I looked through half a dozen JS libraries to do syntax highlighting. In the end, I chose jQuery.Syntax. This is now integrated into Yelp, and syntax highlighting works with appropriate values of the mime attribute. Obligatory screenshot:
A big thanks to Openismus for hosting the hackfest, and to Kat and David for putting up Phil and me. And of course, thanks to the GNOME Foundation for their sponsorship.
Earlier this month, I attended the GNOME accessibility hackfest at the AEGIS conference. My goal was to start planning the accessibility user help for GNOME 3.0. The documentation team often doesn’t understand the needs of users of accessible technologies, and understanding user needs is the first step to writing good help.
I got Joanie Diggs started working on Orca help, and Brian Nitz on Accerciser help. I led them through the basics of planning topic-oriented help and helped them revise their plans. It’s always interesting to teach people topic-oriented help with Mallard, and to see what they grasp quickly and what needs more explanation. It helps me develop my ability to teach people to write.
I also got a much clearer sense of how we should work accessibility information into our desktop and application help. The entire team helped me understand what types of information users might be looking for. For example, Joanie mentioned keyboard shortcut reference pages as something that will often be useful to users of accessible technologies.
This led us to a feature idea for Mallard and Yelp. Joanie wondered if it would be possible to aggregate the keyboard shortcut references from across the desktop. This is basically remixing Mallard pages into a new document, which is entirely doable. But in this case, we want to do it dynamically. And for that, we need a tagging system. I once blogged about tags for faceted navigation, and I think those would work for this kind of use as well. This probably not 3.0 material (unless Phil Bull asks for it, because Phil always gets the backburner features he asks for). But it’s a potentially powerful feature that’s made possible by Mallard’s design.
I also watched demos that gave me a better appreciation of the kinds of needs some people have. Tools like screen readers and magnifiers have high visibility, but there are so many other accessible technologies aimed at people with lots of different needs. All GNOME developers should have the chance to see this stuff first-hand.
On a personal note, I left my wallet in a taxi. Brian Nitz and Mario Sanchez Prada spent two hours with me at the hotel where I picked up the taxi, hoping that the same cabbie would come back there to wait for customers. He didn’t, but Mario heroically talked to every single cabbie that stopped there. End result: my wallet was recovered the next day, minus 30€. Thanks, Mario. You’re my hero.
Milo and I will be running an all-day documentation workshop during the GUADEC pre-conference on Tuesday, July 27th. This is an exciting opportunity for you to work on our documentation, take part in collaborative planning, and learn best practices from experienced documentation writers. This is an unstructured workshop with lots of one-on-one guidance. You do not have to attend all day. Come when you like and leave when you’re done.
The workshop addresses both user and developer documentation. We will have a list of topics for both. Choose a topic that interests you to plan, write, and review. Or bring in your own application or library to document. We will help you plan effective content, write clearly and concisely, and review what you’ve written to make sure it meets your audience’s needs.
Documentation is important to the success of a free software project. I hope you’ll join us and learn how you can provide better documentation.
