Wow, I haven’t update this blog since November… long time ago!

I have to say to work has pretty much sucked up my life: have been very busy there (and probably will be more in the future). The cool part is that I have been working with different technologies, most of them unfortunately had to deal with Windows, some of them with both Windows and Linux, but it has been fun.

I’ve been playing around with JNA (Java Native Access), a bridge between the JVM and the underlying operating system: like JNI, but easier to use since what you only need to write is Java code. It all started with the problem of killing a process tree in Windows having only the root process PID: Windows, unlike Linux, will kill only that process PID, and the rest of the tree will be detached from where it was, staying alive.

The old way of killing a Windows process in our software was achieved with some kind of ActiveX magic (voodoo-poison, I say) and the use of the small Windows utility taskkill. Moving to use Windows functions to create processes, taskkill couldn’t be used anymore: what I experienced were strange behaviors (not always killing all the processes), and also lots of BSOD (still don’t know the exact cause, but removing the use of taskkill resolved the issue). Finding a way to kill a process tree in Windows has been a hard task: looking into MSDN is kind of a mystic experience. I find it a mess. But as always, when you find the solution to your problem, you find it easy and wonder why you didn’t think first about that.

So, to sum it up, if you need to create a process that spawns other processes, and you need to kill that process tree, these are the Windows functions from the kernel32.dll I used:

There are other things it is necessary to take into account, like the creation of the necessary structures, but basically you need to create a job object, create the process and attach it to the job object, and when it’s necessary, terminate the job object. All of this has been done with JNA, writing only Java, and is pretty robust: I tested it on a remote computer for 7 continuous days, creating and killing more than 500000 processes in batch of 4-5 processes at a time, processes that didn’t last more than 5-6 seconds (I even tested it for 3 days with 2-3 hours long processes).

An interesting part has been finding a way to check if a process was still alive, or had completed its run or had already been killed. The first implementation for this was using GetHandleProcessCount. Basically this functions checks how many handles a Windows process still has open, but with such many processes being created in a short timespan, I experienced OutOfMemory exceptions in the JVM (probably caused by many JNA Pointer objects being created and not cleaned up in time by the GC, but I didn’t investigate the cause). The solution has been using the WaitForSingleObject function, monitoring its return state. I only hope the API will not change with some of the too many Windows updates…

Now I’m playing with some really cool stuff: numpy and scipy. I’m trying to “embed” Python into our software, or at least to use numpy and scipy libraries and routines to avoid having to write complex mathematical algorithms when there are already valid and strong ones out there, and also to be able to write internal routines in an easier way with Python. I’m running some comparative tests right now (my computer at the office is still running): I’m trying to see if the same algorithm written in Java is slower or faster than the numpy/scipy internal functions. Right now I’m doing 1500 iterations over square matrices ranging from 10×10 to 700×700 calculating the determinant, and tomorrow I’ll implement the inverse of the matrix. Right now, looks like numpy is faster than Java on matrices from 150×150 and up.

Funny times ahead… also because on March 19th I’ll be heading to Chicago for the Desktop Help Summit with Shaun, Paul, Jim and other cool guys! Looking forward to that!

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:

It’s not secret that I started a new job and that I’m now working for a closed-source company (even if sometimes I have to work with my beloved Linux, but unfortunately that’s rare).

Before starting, I thought I would have found some great docs, describing the works of others, API documentation, internal guidelines, flow-charts, diagrams, whatever; I thought I would have found the basic “infrastructure” that makes a developer work.

I was wrong.

Actually there is documentation, but it’s only the end-user documentation, no real internal documentation. No documentation to help you speeding up with your work, to understand how things work. No (useful) comments in the code.

What would have taken you 5 days of work to accomplish, (exaggerating) will take you two weeks: you have to ask someone else in the company, but maybe they don’t remember or didn’t write that particular piece of code, or didn’t work on that implementation.

Documentation is important, from the end users to the developers, if you want your project to self sustain, if you want to ease the life of other people, and if you want your project to live a long and prosperous life. People were not in your head (and are not in your head) when you wrote that strange thing. 1-2 years from now you could be working for another company, what would be of other people who are trying to understand what you wrote? How would people easily understand how things work in a complex environment?

But luckily, things they are a-changin’. They are now realizing that they need documentation, that they need documentation in the code, and that they need to document things. A small victory.

Lesson learned: next time you do a job interview, if you don’t know the company, ask what are their internal standards, guidelines, and if there is documentation. You can understand a little bit of the level of professionalism of it.

Tonight, around 18UTC, we had a great surprise: a (almost?) famous radio show on an Italian national radio station, talked about Ubuntu and the very coming new release.

The called us at around 16UTC asking for somebody from the Italian community from Milan to do a live radio show… bad timing, we hadn’t anybody ready for doing that in such a short notice, but some of our locoteam members managed to do a great job.

The show ended up being pretty cool and really funny (since they called one of us the “Bill Gates of the moment”! 😀 ).

Podcast (in Italian) will be available probably tomorrow from here.

Happy Karmic release tomorrow!

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=""
 type="guide" style="2column"
 <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="" date="2009-08-31" status="done"/>
 <credit type="author">
 <name>Milo Casagrande</name>
 <name>GNOME Documentation Project</name>
 <include href="legal.xml" xmlns=""/>
 <title>Internet Relay Chat (IRC)</title>
 <section id="manage" style="2column">
 <title type="link">IRC Chat Rooms and Conversations</title>
 <title>Chat Rooms and Conversations</title>
 <section id="problems">
 <title type="link">Common IRC Problems</title>
 <title>Common Problems</title>

And this is the page as it is right now:

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=""
 <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:

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.