archivio

GNOME

I should have blogged more about it, but I already suck at blogging (I have to improve this), and also the Internet connection was not really working well with my computer at the conference (now I’m using the hotel connection!).

One world: AWESOME.

My first GUADEC, and I’m really enjoying it.

A lot of interesting talks, lots of great people, and also lots of work to do.

We had the documentation workshop the day before GUADEC started, and it has turned out really cool and interesting: lots of people are interested in documentation, users and developers documentation; and this is absolutely great!

We had interesting discussions with the Anjuta developer, the Evolution developers, people from Openismus, and many other I can’t probably even remember the names (apologies for that!).

Phil and I have also been working quite a lot in these days: Phil on the what is going to be the new GNOME users help, me mostly on the Rhythmbox docs.

Today we will have the BoF room at GUADEC for us and we will brainstorm a lot on new topics for the GNOME users help. If you want to help us out, or just to hang around and see how we work, please join us!

Last but not least: there are rumors about having a developers documentation hackfest, probably in Berlin, thanks to Openismus. It’s not confirmed yet, but it would be absolutely great! (I hope I can have days off from work to help out with that too).

Sweating and sweating, I’m trying to get this post out… it’s 12 days that I can only use one hand: I dislocated my right shoulder, and will be like that for the next few days, wearing this tutor thing that keeps my arm blocked, and keeps me very well warm (not that in this period I needed that…).

But I’m not writing for that, I’m writing for this:

Yeah, the Ubuntu for Non-Geeks: 4th Edition.

I think it is better if I leave you to our own Phil Bull blog post describing the book, since he’s one of the author:

http://philbull.livejournal.com/55089.html

I had the opportunity to read the book while I was reviewing it (thanks to Phil that mentioned my name to someone!), and I have to sat that it is a very well written book, easy on you. A worth read if you are moving your first steps in the Linux and Ubuntu world. Spread the voice, it’s a really good book!

Oh, and by the way, I’ll be at GUADEC! (I’m really looking forward to my first GUADEC!) And remember, we are holding a documentation workshop on Tuesday the 27!

A big thank goes to the GNOME Foundation!

(Time taken to write this blog post: almost 20 minutes…)

Today was the GNOME Docs meeting day, a planning session for things to come in the doc world of GNOME.

We needed to plan a little bit of work for the coming months (one or two months, not much more), and we decided to focus ourselves on small applications help, something in the order of small games, the calculator, and so on. This will be a good exercise for writing help for an application, and a good learning moment to learn Mallard and topic based writing.

Speaking of games help, since Mario Blättermann ported the Tetravex documentation from Docbook to Mallard, we said: “Why don’t we start from that, and see how we can expand it and work on it?”. Tetravex is not that complex game, and should be pretty easy (and fun) to work on what Mario created.

We wrote down a basic structure for how a game help should (probably) be structured, and it goes in the form of:

  • Gameplay (Introduction)
    • Basic Gameplay and winning scenario
  • Strategy
    • Multiple pages if necessary
  • Multiplayer
  • Tips and Trick

It’s a really basic structure, probably it’s not complete and it will need to expand as we move forward and we reach new kind of games, but for a starter, we think that should work. I’m not going to explain each of them, I think they are pretty straightforward and self-explaining.

So, if you out there would like to start a new experience in the wonderful world of GNOME Doc writing with a light task, we might need your help in writing games help.

Get in touch with the GNOME Doc team at: http://live.gnome.org/DocumentationProject.

Wow, long time no post on this blog… need to remove some dust from here…

Lots of things happened in the meantime that dust was settling: moved into a new city, found a house (or at least something that can be considered so), started a new job, done the usual round of translations and some GNOME-docs related activities (even if not that much since the translations period was on).

But we are here to talk about our beloved Mallard and GNOME docs.

During the last GNOME Doc meeting Paul had a great idea: that we needed to show a little bit of the process that has permitted us to write the shiny new Empathy help, along with some code snippets and how I/we have brainstormed on the topics, how we’ve sorted them and all that jazz.

So let’s dive into this new experience.

I chose to talk and describe a little bit the IRC section, since it has been reported (in the survey we ran) as one of hardest thing to set up in Empathy (and we hope that with this new kind of help it’ll be a little bit easier than before, or at least understandable).

When I “sat down” and started to brainstorm on the topics that could end up describing how to use IRC, I was helped by the survey we ran back in June-July: I already knew that users found it difficult even to “set up an account” (“setting up” an IRC account is not correct, since you don’t really register anything, and Shaun addressed that during the review and the last phases of the writing). So the very first topics that came to mind were:

  • Creating an IRC account
  • Joining an IRC channel
  • Starting an IRC conversation

I started by creating the skeleton of those pages, they were empty, since I needed them to be able to “play” with them in the main index page, to see how to sort and group them, and which words to use. In the meantime I was using Empathy with my IRC account, ‘cause I needed to focus on that feature and see what other things I could do, and came up with other topics:

  • Favorite rooms
  • Nickname password
  • Sending files
  • Problem with the nick

During the first phase of the work on these topics, they where in the same group of all the other text-based conversations (you can see something here in one of my previous post, even if in that one the topics were already grouped), but that wasn’t working out for me, and so decided to group them in a “master” page were all IRC topics would have be. This is the final code-result for the “master” IRC page:

<page xmlns="http://projectmallard.org/1.0/"
 xmlns:e="http://projectmallard.org/experimental/"
 type="guide" style="2column"
 id="irc-manage">
 <info>
 <link type="guide" xref="index#text-conv"/>
 <desc>How to use IRC with <app>Empathy</app>.</desc>
 <revision pkgversion="2.28" version="0.1" date="2009-07-25" status="draft"/>
 <revision pkgversion="2.28" version="0.2" date="2009-08-14" status="review"/>
 <revision pkgversion="2.28" version="0.2" date="2009-08-27" status="review">
 <!--
 <e:review by="shaunm@gnome.org" date="2009-08-31" status="done"/>
 -->
 </revision>
 <credit type="author">
 <name>Milo Casagrande</name>
 <email>milo@ubuntu.com</email>
 </credit>
<!--
 <copyright>
 <year>2009</year>
 <name>GNOME Documentation Project</name>
 </copyright>
-->
 <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
 </info>
 <title>Internet Relay Chat (IRC)</title>
 <section id="manage" style="2column">
 <info>
 <title type="link">IRC Chat Rooms and Conversations</title>
 </info>
 <title>Chat Rooms and Conversations</title>
 </section>
 <section id="problems">
 <info>
 <title type="link">Common IRC Problems</title>
 </info>
 <title>Common Problems</title>
 </section>
</page>

And this is the page as it is right now:

http://library.gnome.org/users/empathy/2.28/irc-manage.html

No topics are hard-coded in this page, all the linking magic happens in gnome-doc, we don’t have to worry about creating the links. We only have to decide that one page should be linked from another one (or that one page should contain a link to another one), and that’s it. With Docbook (at least for how I’ve been using Docbook) you insert the link of the page in the page, you don’t declare a page as linked.

During the writing work, one of the topics has been a little bit “tricky” to write: the “favorite rooms” one. Why? Because the procedure is common to all the text-based group conversations, is (probably) most used with IRC (there are also Jabber-rooms, but personally I don’t know how much they are famous or of common-use), and there are three different “actions” you can do within a “favorite rooms”:

  1. Set a room as favorite
  2. Join one of the favorite rooms
  3. Manage favorites

Using a per-page topic in this case made no sense to me, the topics were short and direct. A single page, interlinked from the IRC and group conversations topics, would have worked out pretty good in this case. This is the part of code that does the interlinks trick:

<page xmlns="http://projectmallard.org/1.0/"
 type="topic"
 id="favorite-rooms">
 <info>
 <link type="guide" xref="index#text-conv"/>
 <link type="guide" xref="irc-manage#manage"/>
 <link type="seealso" xref="irc-join-room"/>
 <link type="seealso" xref="group-conversations"/>
 <desc>Set, join and manage favorite rooms.</desc>

The type attribute tells us where this topic will be linked from. In this case the topic is linked from two guide pages and is also inserted as seealso links.

And here is the favorite room page:

http://library.gnome.org/users/empathy/2.28/favorite-rooms.html

This is just a little bit of the process and how things work with Mallard, and these are some of the lessons I learned during my journey:

  • Do surveys or try to gather information from users. You don’t usually write documentation for yourself.
  • Start brainstorming before writing, and even before using the application you are going to document. And if you don’t know the application, that’s not necessary bad.
  • After the first brainstorm, use the application and take notes of what you can and would do, and how you should do it and how you do it.
  • Before really writing, create a skeleton (just the titles and nothing more) of what you will write and see how it works out in the overall help.
  • Think carefully about the words you will use: weigh them and see if you can use simple words (even translators will be happy!).
  • Try to think and be as a normal user as possible (hard part!), but don’t forget the advanced ones.

Today I was looking at the structure of the new Empathy documetation so far, and I was thinking about the new topics that need to be addressed. Looking at the actual layout, I thought: “And now, where do I insert these topics?”. “In which category do they fall under?”.

So, this is the actual layout:

Old Layout

And this is the new one I’m thinking of, with some of the new topics (those are just there to test the layout and nothing has been written yet, wordings might change):

New Layout

What do you think? Suggestions about the wordings? Does “Text conversations” make sense as opposed to “Audio and video”?

I think I have to find a way to have fixed-width columns in the two-columns view, since I don’t like the “Text conversations” section in that way.

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 Way of the Mallard

The English Man

To this:

The Italian Job

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 Old Way

The Way of the Mallard

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:

mallard-rocks

tame-duck

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.