Just a reminder-kind-of-post: three days from now the Empathy Users survey for helping out the GNOME Documentation Project will be closed. If you would like to help us out writing a better documentation and to help Empathy be a even better application, please spend some minutes doing the survey. It’s here: Empathy Users Study.

Thank you, and sorry for the spam!

Playing a little bit with Mallard, prompt by last GNOME Documentation Q&A session and by Shaun release of gnome-doc-utils 0.17.2, I tried to see what is the situation with Mallard and translations using the xml2po tool.

Well… looks like it works.

From this:

The English Man

To this:

The Italian Job

Well, it’s a start, and it’s almost working. There are a couple of descriptions that are still in English even if they have been translated, and I don’t really understand why those are still in English.

Anyway:

• Nothing has been done on xml2po to make it works
• After converting from PO to Mallard two files, since you have to convert one file at a time, I got bored and I wrote a stupid Python script
• Future looks bright and we might be able to ship Mallard doc with the 2.28

Don’t forget:

• Tonight, at 9pm UTC, there’s the GNOME Doc team meeting (#docs in GIMPNet)
• If you haven’t done it yet, take the Empathy survey to help the GNOME Documentation Project!

We’ve seen it from the inside, and we’ve seen it from the outside, in which other way can we see it? From the user way.

Since we are going to rewrite almost everything from scratch with a new way of thinking documentation, we need users help. We need you out there.

You, user of our beloved desktop and applications could be part of this process. Well, actually you should be part of this process.

We want to produce the best documentation “evar“, and to do that we need to know all the problems you encounter, all the actions and all the tasks you do with the desktop and the applications. Here we will focus on one single application: Empathy.

If you are not a user of Empathy, that would be great too. You have a fresh mind and you are not used to it, you will probably have a different point of view over regular users and could see things in a different way, with a different eye. We need you too.

What we would like to achieve with this is to gather as much information as we can about what you do with Empathy and what you would like to do with Empathy but don’t know how, what is easy and what is not. This will help us write a better documentation and maybe also address some of the problem with the developers. Who knows!

How can you do this?

First of all, install Empathy (it should be not that difficult: look for a package named empathy from your Linux distribution, if it’s not installed by default).

Then, start using it, play a little bit with Empathy and think of all the things you would do, but don’t know how to do, or all the things you don’t find clear in the graphical interface: incomprehensible words, whatever… (for this, please try to use the English version of the program: if you find words that are incomprehensible in your language, that’s more likely to be a translation problem, even if it could be related to the English word being incomprehensible even to translators; but please, report the English ones).

When you feel comfortable, spend some minutes completing this little study, just a single click away: GNOME Documentation Project – Empathy Users Study.

It’s not a professional survey/study, we are trying to do our best. As somebody said at WOSCON, “help [us], to help you” cit. If you even would like to do this survey in your own language, tell me, I’ll share the Google doc with you, but you have to provide English translation of the final results.

This little survey will be open for two weeks: it will close on July 7th. Spread the voice!

PS: Tomorrow at 7pm UTC on IRC (#docs in GNIMPnet) there’s a Q&A session with the GNOME docs guys. Stop by and say hello!

So it has been talked about Mallard and (a little bit of) what it looks like under the hood, but how does it really look like to our eyes? What are the differences between the old and the new way?

Well, it’s almost like comparing Mallard ducks with Wood ducks.

The Old Way

The Way of the Mallard

The two approaches are different.

In the old way of thinking, we had a big-one-huge-file (OK, we could have split it up, but the end result would have always been a massive document) divided in chapter, sub-chapter and so on with (almost) one single fixed flow of the information. It felt more like a book.

With the new way, we have smallest chunks of information that we can group how we like, easy to move from on place to another, that address a small task users will be likely to do or have the need to do.

And this is also the hardest part for writers: finding all these tasks.

It’s not perfect, nothing is and will ever be, but it’s a great approach for solving the documentation problem in GNOME (and maybe others can build on it, extend it or do whatever they feel to do with it). It’s probably going to be hard to rewrite all the docs GNOME has from the old way to the Mallard way, but we can do that and it’s not necessary to do everything in a rush. We have fixed goals for the 3.0, and from that moment we will move on with new goals.

Obviously, if you would like to jump in the doc-writing task and help out speed up the process, we’ll be happy!

If somebody out there would like to find out more about GNOME docs writing, there is a Q&A session on IRC (#docs channel on GIMPnet) scheduled for Wednesday 24th at 7pm UTC for one hour (and more). We will be there, come with your questions!

So you heard a lot of buzz around documentation (”because docs are sexy” cit.) and about Mallard. But what is really Mallard?

Mallard is an XML based syntax for easy writing topic based documentation created by Shaun McCance, our fearless GNOME doc leader. You can find the specification and more tech details here: http://live.gnome.org/ProjectMallard

To read Mallard written docs you need a help browser like Yelp built with Mallard support, plus all the gnome-doc-utils tools Mallard-enabled (they have been released to the public and will ship in GNOME 2.28. Read more here)

Here I will try to show what the Mallard syntax looks like and how to create an easy topic based doc in a simple way. All Mallard files have a “.page” extension and the smallest Mallard document consist of at least two .page files: one fixed-name file called index.page (like good old HTML) plus a topic-name.page file. That’s it. Nothing more. You can have also a single index.page file, but that’s for now probably pretty useless.

The index.page file is the “guide” where all the magic happens: this file is where all the topics will be shown and will usually be the starting point of your Mallard document. Let’s create one simple file and let’s give this document a name: Mallard Rocks!

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
<title>Mallard Rocks!</title>
</page>

The attribute type here makes the difference between a guide-type and a topic-type kind of page. When you are creating the starting point for all your topic-based files, always use guide and call the file index.page.

Let’s deep in the topic-name.page file that I’ll call tame-duck.page:

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="tame-duck">
<info>
 <link type="guide" xref="index" />
 <desc>How to tame the duck</desc>
</info>
<title>How can I tame the duck?</title>
<p>
It's very easy:
</p>
<list>
 <item>
  <p>Have at least the 2.27.1 version of <app>Yelp</app></p>
 </item>
 <item>
  <p>Have at least the 0.17.1 version of <app>gnome-doc-utils</app></p>
 </item>
 <item>
  <p>Read the spec at <link href="http://live.gnome.org/ProjectMallard">live.gnome.org</link></p>
 </item>
 <item>
  <p>Join the GNOME Documentation Project!</p>
 </item>
</list>
</page>

Very easy. The syntax is also simple and it covers all the needs of the GNOME doc team: if you need something more in it, special markers or whatever, buy some beers to Shaun and he will add them!

There is an informal convention about file naming schema in GNOME:

• don’t use: a, an, the, in…
• use dash to separate words
• no capital letters, all lower case
• try to keep the name as short as possible and “topic-based” (the file name is the value of the id attribute!)

Hopefully, other doc teams will use the same convention.

The cool part, where magic happens, is in the info section of the document:

<info>
 <link type="guide" xref="index" />
 <desc>How to tame the duck</desc>
</info>

It tells Mallard to insert the document as a topic of the index.page using the description in <desc></desc>. The final result:

You can also see additional magic in the Further Reading section: there are see-also links writer-definable and the More About that are also auto-added.

Everything I said here and much more is covered in the Mallard pages in a more-professional way. Give them a look, that’s the future of our docs.

It’s always hard to get back to your usual-life-routine after spending some days hacking or at great conferences with such wonderful people and in a lovely location. Well, at least it’s always for me. There was a commercial running here in Italy of a famous Italian cruise company, where people after the cruise experience find themselves crying or in group-therapy remembering the great moment: I’m always a little bit like that.

The Writing Open Source conference (DENT:woscon,woscon09 TWIT:woscon,woscon09) has been really interesting, professionally and humanely. I have a lot of information over some big Tomboy notes that I will be reading and re-reading in the days coming, they will be always open on my desktop when I have to deal with docs.

But it has not been only a conference: Writing Open Source is now a “community” (DENT:wosdocs TWIT:wosdocs), a central point for open source tech writer and for all the tech writer out there that would like to get involved in open source or that would like to share their experiences with us (we need them and we need you!!).

So, come on in, jump on the docs writing bandwagon, we are as crazy as woolly mammoths can be!

I already blogged a little bit about the first two days of the conference, I didn’t cover yet the last one: the sprint one. We formed two working groups: GNOME and Drupal. The Drupal one worked on the Writing Open Source community website, while we have been working for laying the foundations of what will be the new GNOME 3.0 Documentation: Mallard is among us!

We have been working with Lynda Chiotti and Janet Swisher on how we can and should work, how to organize and plan the doc writing activities, brainstorming on the topics we should cover in the documentation and how to create “personas” for documentation. All the day we have been working on closing some GNOME-docs bugs (Paul) and we started to port Empathy documentation to the new topic-based approach using Mallard (me and Phil, the repository is on gitorious) while Shaun was dealing with the Mallard spec and supervising our work. We also brainstormed about how to plan the work for the 3.0 release.

The plan for the 2.28 release of GNOME is to have the Mallard spec done (well, at least almost done), Yelp ready to use Mallard and Empathy documentation written topic-based with Mallard. There are some works to be done with regards to i18n/l10n and Mallard XML files and the build structure, but we would like to have everything at least ready for the 2.28. The big goal, at least for me, would be to have Empathy ships Mallard doc on release day, will see…

A big hug goes to Emma and her mother for the organization and for feeding us with wonderful breakfasts, lunches and suppers (or dinners, or teas? whatever…) and to all the people that there were with us: Paul, Phil, Shaun, Janet, Lynda, Addi, Dru, Jim, Richard, Dinda, Jeffrey, DB… (I know I forgot someone, but I’m not a sound-learner, I’m visual. So please apologize!).

PS: the DENT|TWIT:tag[,tag] notation is my new social-exchange notation

Well, in 7 hours it will be WOSCON Day 3, but I couldn’t not blog about today. Today was the unconference day: we discussed of whatever came to our mind.

The day started with Shaun (finally) presenting Mallard to the public, the new markup language for writing topic based documentation that GNOME will use in the future. So, great times ahead for doc writers and for all GNOME documentation! Mallard rocks! Quack!

The day went on talking about translations, mostly related to the translation of documentation and how we can try to make translators happy translating documentation: first of all we need great and updated documentation to enforce a great string freeze GNOME-style here too, and that would be way cool. Second thing is great rocking topic based documentation: it should be a little bit easier for translator to do their fantastic work (obviously we need xml2po to work with Mallard, but we know somebody will take a look at it).

Other talks of the day have been on FLOSS Manuals and what they are doing: writing a complete book from 0 in 5 days. Amazing.

Last talk of the day was on certification programme creation: a wonderful talk to get into this (for me) new topic. There’s a lot of potential for open source here, really. It’s something that need to be followed.

It has been a great day. We also went to a small trip just outside Owen Sound to a waterfall. Great place in the woods, a relaxing moment away from computer screens.

The night has been total fun! Total! No words describing all the laughs we had, you can check out the #woscon09 tag on identi.ca or twitter to get an idea…

BANG!

I’m at the Writing Open Source Conference (jet-lag kicking in) with the other GNOME (and Ubuntu) guys, writing from the Ginger Press Library Cafe right now. First day has been very productive and interesting, chats are still going on here at the Cafe in front of some good beers and something to eat. Great people!

We started the day with a documentation license overview from the point of view of a (real) lawyer and how to work with licenses and the community involved in documentation writing. An absolute helpful talk about user-centered documentation design: absolutely great and insightful tips on how to organize the work on documentation, from start of implementation to the final product.

We also talked about fame, fortune and how to earn a living writing documentation. The final talks were about how people learn and how we can use this information when writing documentation (by Belinda Lopez from Canonical) and on documentation community.

A really really interesting day. Looking forward for tomorrow!

I’m still at the hotel waiting for my cab to the airport and am using the last minutes of free wifi connection before heading back to Italy.

This travel and great experience is over, I already said that, but in 10 days a new travel awaits me. I’ll be heading to the Writing Open Source conference in Owen Sound, Canada (with other guys from GNOME and Ubuntu too) thanks to the GNOME Foundation, the kind GNOME Travel Committee and Shaun McCance (and I also think Intel for sponsoring us, but I’m not really sure).

I’m really excited about this travel and about the conference. We, with the GNOME 3.0 release plan, are facing a great moment for reshaping documentation, for GNOME and for all downstream projects out there that builds on GNOME. There is Mallard that is shaping out as the new format for writing GNOME documentation and we will learn more about it during the conference. I’m also going there with some crazy ideas about documentation for GNOME, you can read them here.

denttwitOn the third day of the conference I added an “Empathy documentation sprint”, I hope to have the chance to speed up a little bit the writing of the documentation for Empathy with the precious help of some professional doc-writers, since I would really like to have a 100% features-full documentation for the 2.28 release (there is also the possibility to have Empathy in Ubuntu for the next release).

I’m thinking also about adding a “Gwibber documentation sprint”: gwibber rocks, and if you dent (or twit) a lot you should try it. Right now gwibber doesn’t ship with documentation and since even this one has great chances to get included in Ubuntu for a full-social-web experience, I think it needs some love.

Now it’s time to take the cab. Again: thank you all UDS guys & girls, you really rock!

UDS is (almost) over and what a week has it been! Wonderful!

Lots of good sessions, talks, news and previews and people! Today we had a lot of translations related sessions and we decided to take a picture with all the translation-really-involved people that there here.

So, here we are:

From left to right:

• Me
• Jeroen Vermeulen
• David Planella
• Adi Roiban
• Henning Eggers
• Kyle Nitzsche (OEM team with an eye on translations)
• Arne Goetje
• Danilo Segan

(For a bigger picture, when I get back home I’ll send you)