Skip to content

Documentation

GNOME Docs Hackfest (Part I)

dsc02277.jpg

(A duck at Inglis Falls, in Owen Sound, Ontario, home of woscon09. If only it had been a mallard…)

Milo Casagrande, who attended woscon09 with the GNOME Docs team last week, has written an introduction to Mallard.

Milo and Phil spent Sunday’s hackfest creating the first Mallard document for use as a help file within an application. We chose Empathy, for a few different reasons, including: it will be in GNOME in 2.28; the current documentation is not completed; we want to re-license it from GFDL to CC BY-SA 3.0 and Milo and one other collaborator were the only ones who had worked on it previously (though we fulfill our obligations in re-licensing by the exercise below).

Using the information we learned Friday and Saturday, we spent time planning the document and brainstorming what users want a messaging application to do, and what questions they might have: “How do I….?”.

From there, and with great gusto, Phil and Milo spent the sprint creating a proof of concept help file for Empathy. Not only is it written in Mallard, which can dynamically link the pages, we are focusing on creating topic based help, rather than tasks that take a user step by step in performing an action. Phil and Milo will probably have words with me, but you can follow along on the empathy-mallard branch in Gitorious.

You will need Yelp 2.27.1 and gnome-doc-utils 0.17.1 to see a Mallard doc in Yelp. And now I have to go figure out why Yelp isn’t cooperating with me.

Banshee Documentation

One of the things I learned last weekend at woscon09, was the importance of planning when beginning to write documentation.

With that in mind, and the GNOME Documentation Project’s focus on moving to topic based documentation, the goal of writing docs for Banshee is to answer the question “How do I…?” for users.

So let’s kick off writing the first ever integrated help file for Banshee!

Knowing that, have you come across any forum posts, blog posts, information on a wiki, or howto’s about Banshee? Do you know a trick or tip about Banshee most people might not know? You needn’t have written it, I’m just looking for links. If you have some to share, please leave a comment on my blog. (I have an over-aggressive spam filter, but I’ll be actively monitoring it).

I’ve brainstormed my own topics for user help, and have the start of a table of contents, but I’d love this to be a community effort. As I see good information out in the community, my goal is to contact the author and see if they’re willing to help with Banshee docs. The Banshee documentation will be one of the first help documents in GNOME to move to a CC-SA 3.0 license, and if the authors want to help, that’s the only requirement. CC-SA 3.0 automatically gives attribution as well.

My last goal is to write the Banshee docs in Mallard, now that support support for Mallard is in GNOME 2.27. And if you want to help, don’t be intimated by that! We’ll do the markup for you if you’re new to GNOME docs and have good information to share!

I’ve started a docs branch on the Banshee repository on Gitorious which is where active development will take place.

And speaking of attribution, I can’t take credit for this idea. A big thank you to Emma at woscon09 last weekend for encouraging me to get the community involved.

So what topics do you think should be in the Banshee help file? What information about Banshee have you come across on the internet that should be shared with other users?

Docs Team & Community

dsc02267.jpg

_(The Ginger Press Cafe where the work, talk and laughter happened at woscon09)

_

One of the most important take-aways for me personally from woscon09 were the talks on community. This included Addy’s keynote Friday on herding cats, the challenges that spanned all of our groups, discussion around upstream to downstream and back again, and encouraging new volunteers.

With that in mind, we’re making some changes to the Docs team to improve our community involvement.

Last night, Shaun sent an email to the list detailing some of the changes, including:

  • Community Management
  • Editorial assistance
  • Reviews
  • Upstreaming downstream

And, of course, we are all responsible for writing.

With that said, I’ve spent some time over the last day or two re-organizing our wiki, and have put together a stub of a page around Community.

We will be having our first Q&A session this week, starting tomorrow night at 9 p.m. CST (2:00 a.m. UTC). We are committed to having these meetings, and moving the day and times around to get as much representation worldwide as we can.

The theme of tomorrow’s meeting is a recap of what we learned at woscon09. However, please bring any questions. Want to know how to get involved? What to write? How to use bugzilla? This is an open session, and more than anything, it’s to let folks know that we will be in IRC at a given time to answer any question (within reason). Stop by #docs on GIMPnet IRC tomorrow night!

We’ve also started a Docs Team blog where we will be posting meeting announcements, recaps, and other important information that we wish to share with the community.

Have you ever wanted to help out? Feel you can write technical documentation? Have above average grammar and spelling and want to edit? Translate our docs? Now is the time to get involved. We have lots of exciting things planned for this year, and this is just the tip of the iceberg.

Writing Open Source

dsc02287.jpg

(Inglis Falls, just outside of Owen Sound, Ontario)

My head is still spinning after 3 days at woscon09.

I learned so much and met so many great people. Over the coming days and weeks I’ll be blogging more about it.

Some key things I left with (in no particular order):

  • Know your audience. (True in marketing, and also true in doc writing). Develop personas for your audience.
  • Plan, plan, plan
  • Tons of community management stuff, such as make it easy to get involved, and have tasks ready that are simple (think stuffing envelopes)
  • Speaking of community, we all have similar challenges, no matter the project
  • Mallard exists!
  • Owen Sound is a beautiful small town.
  • I knew this already, but it was reinforced: hacking in person is much more fun
  • I’d rather clean up bugzilla one bug at a time when they come in, rather than spending hours sifting through old bugs
  • There are a ton of things we can do to improve upstream and downstream communication and collaboration.
  • Topic based documentation is much better than task based documentation.
  • Re-writing GNOME docs as topic based help is a mammoth sized task.
  • A few years from now, I’m going to look back and say, “I was there when it first started”.

Lastly: Write every day. You can expect more blog posts, documentation updates, and contributions to GNOME marketing and the web content with that in mind.

And those are just off the top of my head! There was so much more. And if you were following along on Twitter or identi.ca Saturday night, you may not have gotten the jokes without the context of being there, but trust me, I haven’t laughed that hard in a log time.

Thanks again to Emma for conceiving woscon09 and hosting. If you are interested in technical writing, check out the Writing Open Source website, where this brand new community is just getting started. Contribute, read our forums, or read our Planet to learn more about writing docs for free software projects.

Writing Open Source Day 2

We’re just over halfway done with day 2 of the Writing Open Source conference, and today is an “unconference” day in the style of BarCamp.

Conference attendees are giving talks today inspired by conversations from yesterday, other ideas attendees had, and more.

GNOME’s own fearless documentation leader, Shaun McCance, kicked off day two this morning giving an overview of Project Mallard.

shaun-mallard-talk

(Please note that the picture on the projector is a wood duck, and not a Mallard. You’ll have to ask Shaun for the story. Picture courtesy of Milo Casagrande).

Shaun talked about his design goals for Mallard, the benefits of using it instead of using Docbook, and showed it working in Yelp(!), the GNOME help browser. Shaun also discussed and demonstrated Pulse, and you could tell how much passion he has for documentation and the tools involved.

We also had talks about how we can make docs easier for translators (and I showed off Damned Lies, which is so cool, especially considering how little I know about it), how an organization could create a certification program, creating a book in 5 days or less, and my personal favorite, communities. We talked about how different communities that are represented here at the conference work, how upstream and downstream work, what’s not working, how we could be doing community outreach, and why there is a perception that docs just aren’t cool. (Take it from me, docs are sexy! And there will be more to come on that subject).

One of the coolest things for me at least, so far, is finding these other communities, including Drupal, BSD, XFCE just to name a few that are represented here, and how many commonalities we have. Drupal and GNOME might not have a lot of common in how documentation is used, but we have similar challenges and processes. We are making friendships that will help us to create documentation best practices that span communities and one of our goals is build on the success of this conference and keep in contact and continue to share information with each other, and recruit more to join us.

Tomorrow is our hack day, and that should be a blast as well.

Writing Open Source

The first ever (that we know of) conference for documentation writers in open source conference started today in Owen Sound, Ontario (about 2 hours from Toronto). The Writing Open Source conference is being hosted by Emma Jane Hogbin, and a few of us from GNOME are here:

dsc02257.jpg

(Left to Right: Shaun McCance, Milo Cassagrande, Phil Bull and myself).

We’re halfway through the first day, which is keynotes, and the conference is awesome.

Some random thoughts:

  • How cool is it that all of our keynote speakers are women? And our conference overall is 50% women / 50% men.
  • Lots of different projects are represented, including BSD, Drupal, GNOME, XFCE and more.
  • The keynotes are great. All of us have pages of notes, either on paper, in Tomboy or insert your favorite text editor.
  • A quarter of attendees have netbooks. There’s a couple of Macs, and the rest of us are on laptops with Linux. I haven’t seen one Windows laptop yet.
  • Experience ranges from published authors to one individual who’s never contributed but wants to learn.

Belinda from Canonical is talking now, and she has goodies and exercises for us to do, so I have to run. More to come. You can follow along on Twitter or identi.ca with the #woscon09 hash tag too.

GUADEC!

I’m going to GUADEC this year!

In all my travels, I’ve visited almost all 50 states in the U.S., but I’ve never travelled internationally. Now in the span of 30 days, I’ll be visiting both Canada and Europe – and both are related for GNOME events. And I’d like to say a big thank you to GNOME for helping subsidize my travel to both events.

The initial GUADEC schedule was posted this morning, and I’m excited (and nervous) that Stormy’s and my Birds of a Feather session on GNOME marketing was accepted! (Thursday, 10:00 a.m.). I was hoping to fly back home Friday morning, but now I need to find a way to stay to see Davyd‘s talk on Documentation Friday morning.

In related GUADEC news, we at the GNOME Journal are publishing a GUADEC special edition. Are you going to GUADEC? Have an interesting idea for an article – maybe from a talk you want to attend to learn about (and share about with the GNOME Journal audience!) or someone you might want to interview face to face while at Gran Canaria? Let us know, more info is available here.

I’ll be seeing you in July in Gran Canaria.

GNOME Updates

Lots of stuff going on in the world of GNOME for me!

Attended a few meetings last week with GNOME related projects.

This past Sunday, April 19th, the Documentation team met for the first time in a while. Shaun gave an update on the status of Mallard, the new markup language for GNOME Docs; a possible change to how we license docs; an introduction to Pulse and some brainstorming on new ways to bring guides to users.

On Tuesday, the Tomboy team met to discuss the road to a 1.0 release. More exciting though is the news on the work being done around syncing for Tomboy, including a potential online syncing service for users. As someone who’s lazy, and not that technical, but owns multiple computers that use Tomboy, I’m very excited about the potential a syncing service has. (And if you want to help update the Tomboy end user website, please let me know!)

Related to the Documentation news though, I’m happy to announce I’ll be attending the first ever Open Source Documentation conference, Writing Open Source, in June in Owen Sound, Canada. The GNOME Foundation is graciously covering my lodging, and three other GNOME Documentation team members, including Shaun, will be there. In addition to the tracks on Friday, there is an unconference on Saturday, and we will be having a documentation hackfest on Sunday. The hackfest might also be the first public unveiling of Mallard as we start working on all new documentation for GNOME 3.0.

I booked my flight and paid for the conference this weekend, now comes the hard part – the waiting until June.