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="email@example.com" date="2009-08-31" status="done"/> --> </revision> <credit type="author"> <name>Milo Casagrande</name> <email>firstname.lastname@example.org</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:
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”:
- Set a room as favorite
- Join one of the favorite rooms
- 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:
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.