Skip to content

Blog

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.

  • in GNOME
  • 2 min read

Friends of GNOME

Later this week, I have the opportunity, along with Shaun McCance, Phil Bull and Milo Casagrande, to attend the Writing Open Source conference, which is thought to be the first conference to be focused on open source and documentation. We will have keynotes on Friday, an unconference on Saturday, and a GNOME documentation hackfest on Sunday.

GNOME is sponsoring four of us to go from a donation by Intel. Each of us is paying the conference fee out of pocket, and GNOME has subsidized our airfare and lodging (I paid for my own airfare).

Wouldn’t it be cool if GNOME could sponsor more hackfests and travel subsidies for GNOME hackers each year?

If you look at this page, GNOME’s goals from the Friends of GNOME program include:

  • Produce more end-user-focused technology and features through technology-specific hackfests. Hackfests are events where a core team of project developers get together and spend a week in the same place, discussing plans and writing code. They are particularly useful for getting new projects or large features launched (like GTK+ 3.0) or getting a large amount of code written.
  • Provide travel subsidies to bring our worldwide community of volunteer developers together. This enables them to work on existing projects, plan new projects, and work with partners and companies that use GNOME technologies.
  • Support local conferences such as GNOME.Asia, GUADLAC (Latin America), the Boston Summit, GNOME.conf.au (Australia), and Forum GNOME. Local conferences provide a forum for building community, sharing technology, and bringing developers, companies, and users closer together.

And this is just three of the twelve goals the Friends of GNOME program is trying to support!

I understand these are tough economic times. If you can, any support you can give helps. I’d also ask you to consider the “Adopt a Hacker” option at $10 a month. This helps you by being a small amount each month, rather than a larger one time donation, and by donating monthly helps GNOME plan more effectively through having a consistent monthly revenue source.

And don’t forget about the framed GNOME artwork Behdad blogged about last week! The first person who donates at the Philanthropist level gets this one of a kind engraved plaque.

I became a Friend of GNOME this past April, will you?

Linux Journal Readers' Choice Awards

The Linux Journal has recently published the 2009 Reader’s Choice Awards.

GNOME was voted, by readers, as the “Favorite Desktop Environment” garnering 53% of the votes, with KDE in second place at 30%.

From the article:

During the past year, GNOME has reached majority rule status, with 53% of you electing it your favorite desktop environment. This trend is despite the breakneck development of KDE 4 during the past year. Although GNOME garnered only a few more votes than it did in 2008, KDE’s vote count slipped as you’ve warmed to Xfce, Fluxbox and Enlightenment. The long and influential coattails of Ubuntu can only make any presidential candidate green with envy.

Flattering words indeed!

Contrast that to the 2004 Readers’ Choice Awards:

Favorite Desktop Environment

  1. KDE

  2. GNOME

  3. Window Maker

For several years now, KDE and GNOME have finished first and second, respectively, with an ever-increasing distance between the two. This year, KDE received two votes for every one GNOME received. Window Maker holds on to the number three spot, beating XFce by a single vote. No one said “they all suck” this year, and the only write-in voter who expressed frustration said he might try to write his own environment.

(Emphasis mine).

I think the GNOME community should be very proud of the progress made within GNOME, which is reflected in these vote totals.

(Thanks to Claus on the marketing list for pointing out the latest Readers’ Choice awards).

  • in GNOME
  • 1 min read

Hello Planet GNOME!

I would like to thank the Planet GNOME editors (Jeff, Lucas & Vincent) for adding my blog.

A brief introduction – I’ve been using GNOME for 10 years, and I started contributing a little bit on and off a couple years ago, mostly with the Marketing team on the GNOME web revamp, Tomboy documentation and also GNOME Journal. This year I’ve become much more active, joining the Sysadmin team, submitting a number of documentation patches, becoming the release manager for GNOME Journal, and spending more time with the Marketing and Web teams. I’m also the former Community Manager for Foresight, and still active in the Foresight community.

By day, I work for a software company in product management, focusing on anti-malware products for Windows . Away from my computer, you’ll find me spending time with my wife and 3 children, watching (American) football and slowly learning how to cook.

You can also find me on Twitter and Identi.ca. I’ll also be attending my first GUADEC this year, so please say hi!

I’m humbled to be here – I’ve been reading Planet GNOME for years, and I’m thankful to be part of the community.

Meet Snowy, Tomboy's best friend

Tomboy was one of the first GNOME products I contributed code (documentation) to. It also is one of my all time favorite apps and one I can’t do without on a day to day basis. Whether it’s jotting down ideas I don’t want to forget, to-do lists, or organizing the release plan for the next GNOME Journal, I always have a bunch of notes open.

A few weeks ago, I finally got around to trying to sync my notes via sshfs on my desktop and laptop. And, to be frank, it was a pain in the butt, and not documented well. It’s working, but I don’t think it’s working quite right yet.

Which is why I couldn’t be more excited for Snowy. Snowy is a web application for synchronizing, viewing, sharing, and editing your Tomboy notes online. Snowy will power the Tomboy Online service, and in addition to syncing your own notes online, let you also share and edit with friends.

Best of all, Snowy will be Affero GPL licensed – so if you want to run your own Snowy server and sync your notes there, you can! (It’s similar to identi.ca – laconica is the open source software that powers identi.ca, and you could run your own microblog server on laconica if you wanted to).

I recommend reading Sandy Armstrong’s (lead developer of Tomboy) blog post on Tomboy and Snowy (including an early screenshot), and Brad Taylor’s (lead developer of Snowy) blog post introducing Snowy. (And the title of this blog post is stolen right from Brad’s mouth).

More to come!