I posted before about the magic search+location entry I’m working on for Yelp. The general goal is to reduce Yelp’s interface to the smallest number of elements possible. The drop-down is very terse, though, and doesn’t give you a lot of information.

One of the things I really like about Mallard guide pages is that they present topics to you with more verbose text descriptions. This allows readers to scan titles quickly, while still letting them check the description for assurance before committing to a click. I wanted to bring that to the location dropdown.

Another problem is that the search entries in the dropdown gave no indication of where they’re searching. For 3.0, we want to have searches be per-document by default, with a link to search the entire help system instead. This would give you two entries in your history that look exactly alike, but return different search results.

So I played around with using two-line entries in the drop-down. For normal page entries, this is the same title and description you would see if it were on a guide page. For search entries, you see the search terms and where it’s searching.

Obligatory screenshot:

I’ve been meaning to follow-up on Shaun’s recent bog post about “Explain More” when writing user help. Zonker’s blog post this morning on how to write an interview finally motivated me to get this blog post done.

One of my favorite sayings in a work environment is “Plan the work and work the plan”. This applies to writing as well.

One of the two major takeaways I had last year after attending the first Writing Open Source conference was the importance of planning. At least for me, almost of all the heavy lifting and hard work is done in the planning phase. (Not that writing and editing are easy either, but the planning for me is where my brain works the hardest).

When I was in school, especially high school, all of my English teachers required an outline when writing a term paper. School was fairly easy for me and I’d just write the paper and then do the outline. Oh, how I wish I had listened to them and learned those skills then!

It’s fascinating to me reading novels and then reading about or listening to an author talk about the years they spent researching their book. After last year, it’s finally clicked for me. (Having just finished io9’s recent book club selection, The Windup Girl, by Paolo Bacigalupi I found his answers in the book club Q&A session fascinating, especially his research on Thailand and the Thai culture).

Planning your writing will help you connect with your readers, stay on message and help you faster. (Faster isn’t always better but you may spend less time getting stuck or if you do get stuck, be able to write the next section that you’ve planned and come back and finish where you were stuck).

Whether it’s user help, a blog post or an interview, spend some time thinking about what you want to write about and who your audience is. Your readers will thank you.

I just wrote a short tutorial on how to embed SVG in Mallard. Because Mallard is designed well, you can easily mix other XML vocabularies into it. That means that simple SVG in Mallard wasn’t a good enough challenge. So I made it so that embedded SVG can use Mallard’s linking mechanism. With a bit more work, we could probably even dynamically generate text labels in SVG from Mallard page titles. And that could be the framework for some nice charts and diagrams.

I have permission to include a few pages from the Definitive Guide to PC-BSD in the next issue of BSD Mag and could use some help determining what to submit.

The audio for my SCALE 2010 talk on BSD for Linux Users is now available in mp3 format. The accompanying slides are in PDF format.

The Best of FreeBSD Basics is now available for the Kindle.

Last week I packed all of my belongings in a storage unit and left my house of 10 years. I've been paring down my possessions so that when I left I could comfortably fit all that remained in a 5x5 ft (1.5m) unit. I stuffed all of my clothes, a few important books, and electrical gadgets in a duffel bag and carry-on. That is what I will live out of for the foreseeable future. I've chosen to roam and I don't know when or where I'll stop. I have some preliminary plans to stay in Europe for most of the next eight months or so, but who knows where I'll be when. I'm in Dublin, Ireland right now, will be at DrupalCon San Francisco in April and intend to live in Copenhagen, Denmark this summer. That's about all I have sketched out.

The last year has been intense in a lot of different ways. I've also been in a deep depression for most of it. No need to get into lots of details, but one of the casualties of all this was my relationship with Colleen. It ended in October, after nine years together. Needless to say, we are both deeply saddened, but determined to work out a lasting friendship. I stayed in the empty house for as long as I could while we figured out what to do with it. Neither of us has any desire to stay in the shell that used to be our home. Aside from the ghostly experience of living in the house, Maryland itself doesn't have much to offer me these days. Most of my good friends from the area have moved away. The house is a quiet place of trees and memories, which I do love, but it also makes me feel cut off, adrift. And sad. Maryland is simply no longer a home for me, and returning there makes me feel empty instead of comforted. More has changed here than my relationship in just the last few months (not counting all of the shit from last year); the deeply wooded lot next to me has been ripped up (every single last ever-loving tree!) for new houses, my cats moved out to live with Colleen, and my elderly next-door neighbor killed himself on his front steps (that image is forever burned in my skull). The time has come to move on. I feel like I am living in a parody of my "home." It has been a good home, a great home, but my definition of home is changing. Or maybe my definition is the same but there is nothing that matches it any longer. What it is changing into or from, I don't know, but I know "home" is no longer here.

So I'm heading back into the world of experience and exploration to see what I can find. I'm not even sure what I'm looking for, but I will try (try, try) to have faith in my self that I will know something when I encounter it. That I won't continue to make fatal mistakes (ha!). I will need to work hard to be open on this journey. I'm beat up, fed up, exhausted, and oftentimes not very amused by all of this muckity-muck when I had a perfectly respectable life going on. But there is also a flame in me that is fascinated and pulls me forward in hope, gasping at fresh air. There is excitement mixed with fear and (self-)loathing. I choose to believe this is a cocktail for discovery and growth instead of despair.

So. I am homeward bound but homeless. And I'm OK with that. Let the journey unfold.

The next issue of BSD Mag is now available for download. From the table of contents:

One term of art in technical communication that just bugs me is "content". It's the term we use to describe information when we don't want to be specific about the format (text, graphics, audio, video).

The Free Software Foundation has an interesting take on this term:... using the word ["content"] as a noun to describe written and other works of authorship ... regards these works as a commodity whose purpose is to fill a box and make money. In effect, it disparages the works themselves. ...

The term “content management” takes the prize for vacuity. “Content” means “some sort of information,” and “management” in this context means “doing something with it.” So a “content management system” is a system for doing something to some sort of information. Nearly all programs fit that description.My objection is more on the intellectual side. "Content" is just so vague that it could mean almost anything. It implies "stuff that goes inside something else", which could include, say, peanut butter. I think the term "content" has gained currency thanks to web designers, whose primary concern is the form of a design, with the content that goes into the form being somebody else's concern. But for those of us who provide it, the fact that content fits into a form is a secondary feature.

Unfortunately, none of the alternatives is much better. "Information" and "communication" are nearly as broad. "Knowledge" is also broad, and not all content rises to the level of knowledge in the DIKW hierarchy of "goods of the mind". I mention this merely as an excuse to quote T.S. Eliot's The Rock:Where is the Life we have lost in living?

Where is the wisdom we have lost in knowledge?

Where is the knowledge we have lost in information?The best alternative to "content" that I can come up with is the slightly longer phrase "content assets". While this still relegates works of authorship to the status of a commodity, it at least makes the concept into a count noun instead of a mass noun, and implies that the commodity has some intrinsic value beyond filling a box.

I realize that "content" is already so prevalent that it's not going to be changed any time soon. But I still can indulge in an inward cringe when I read or hear bare-bones "content", and engage in a private crusade to use "content assets" instead.

Several readers have asked for the table of contents to the Definitive Guide to PC-BSD. With the permission of the publisher, here it is:

Interesting reading still exists, even when I'm too busy to blog about it...

The editorial theme for the March issue of the OSBR is Mobile. The guest editors are François Lefebvre from Communications Research Centre, Canada and Thomas Kunz from Carleton University, Ottawa. This month's authors include:

Neil Gaiman continues to be one of my favorite authors (and tweeters). I bought a print of his poem “The Day the Saucers Came” in 2007 when it first came out and finally have gotten around to having it framed. (And I have #69 of 750 made, a nice low number!)

“The Day the Saucers Came” was originally published in Neil Gaiman’s short story collection, “Fragile Things” and was one of my favorite stories included. The fact that it became the first print available illustrated by Jouni Koponen was even better.

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 [...]

The essence of technical writing is explaining. Whether you’re writing an introductory tutorial or a massive reference manual, your goal is always to explain something to the reader. It follows that to be a better writer, you should be a better explainer. And as with any skill, you get better with practice.

Take opportunities to explain things to people. Remember that guy at the gas station asking for directions? Take a few minutes out of your day to help him. Think about his frame of reference. Will he be able to recognize local landmarks? Does he know which way North is? Think about the different ways he could accomplish his task. The route you would take isn’t necessarily the best route to send him on.

Explaining things to people will help you understand how others might think. You get used to the things you know, and it’s sometimes hard to articulate everything to somebody else. You might leave out steps that seem obvious to you. The more you explain things, the better you will become at anticipating gaps in your explanations.

If a colleague asks you to explain your work or your decisions, do it. Don’t treat it like a challenge or a distraction. Explaining will help you better understand the subject: the best way to learn is to teach. And it will help you create things that make sense to other people.

Try taking things a step further and writing instructions for things in life. Sure, it could be about complicated technology, like programming your VCR. But you can write instructions for low-tech things too. If you like to cook, write instructions for one of your favorite meals. Then ask somebody else to cook from your instructions. Remember that terms that are familiar to you might be lost on your reader. Does your reader know the difference between simmer and sauté?

By explaining things through instructions, you practice explaining without immediate feedback. Face-to-face instruction is wonderful, but it’s not a luxury you have when writing documentation. You have to take your skills in explaining things and put them to use in an environment where you can’t see confused facial expressions or answer questions.

Make a habit of explaining better in everyday life, and you will find you’re more able to create things that other people actually understand.

PC-BSD 8.0 (Hubble Edition) hit the mirrors last night and was officially announced this morning. For those of you using VMWare, the VMWare images should be available tomorrow or Wednesday. From the announcement:

Interested in a copy of The Definitive Guide to PC-BSD? Consider pre-ordering from the FreeBSD Mall.

HAST (high availability storage) has been committed to FreeBSD.

In the past few weeks I have been building myself up to get back on track with my role as Doc Lead in the Drupal community. I've been off radar for quite a while now (since last fall) and I'm finally getting my feet under me to tackle the work of docs again. In the time that I was out of it though, it was too obvious that there needed to be some changes in how I (and the Drupal community) approach this whole documentation team thing. There were a few other people out there who had expressed the same concerns to me and so I sat down with them to kick around what we need to change. We came up with two fundamental shifts in how we do things as a team: communication and coordination. I think this will take a lot of pressure off of a number of people, myself included, as well as let the community take even more ownership of documentation and play a role in the steering of the ship, even if the captain sometimes goes AWOL.

There is a post up on the Documentation Team group page which goes into the details about changing our main form of communication (focused on that very group) and the new concept of coordinators for the team. Time to spread the love and put some names and faces to the people who are doing the work. Hopefully this will also create more points of contact for folks who want to get involved but just aren't sure where to go or who to talk to. So if you want to share in the work and make some connections to help you on that road, come play with us over at groups.drupal.org and the issue queue. We have lots of good stuff to get going.

Speaking of good stuff, we also sat down and got ourselves refocused on the big monster goals that really require team effort to pull off. We have cleaned up our Community Initiatives section a bit to make it clearer that our current big project is getting the Drupal 7 documentation up to snuff for a great release. Once we mop up Drupal 7 work, we will begin to focus on creating a new, better home for our docs on a new sub-site in the drupal.org family. That project presents some wonderful opportunities but also a tremendous effort with many moving pieces. So, for now, we really need to get Drupal 7 rockin' out the door before we begin the long haul of a new doc home. Please feel free to dig in the Drupal 7 project or if you have a burning desire to work on an initiative of your own, let us know on the Documentation Team group page.

Big thanks to Jennifer Hodgdon (jhodgdon) for hosting our little powwow out in her home in Seattle, as well as Lee Hunter (LeeHunter) for taking his weekend to fly out to the west coast so we could all sit down and sort some of this out.

(This is reposted from an email earlier this evening)

Hi all, I wanted to give you a brief update on the GNOME Sysadmin team.

Last April, Owen sent out an email outlining changes to the Sysadmin team and a goal of hiring a part-time System Administrator to help coordinate the Sysadmin team. (And we’re getting closer to be the goal every day!)

Last year John Carr oversaw the team and the Sysadmin team was able to work on a number of improvements to the GNOME infrastructure, including a Bugzilla upgrade, installing a CRM system and web analytics application for the Marketing team and Plone, a CMS for a new www.gnome.org.

In October I volunteered to help with coordinating the team as John stepped down and with a new year starting a couple other members have indicated they don’t have time to help right now as well.

We have lots of improvements planned for this year such as bringing a brand new server online (thanks to Jeff Schroeder’s donation!) and migrating services from older servers to the new one, Git and Damned Lies integration, integrating all GNOME servers with Puppet and scoping Tomboy Online. That’s just to name a few – we also have a number of tasks open in Bugzilla in the sysadmin component.

We are looking for two volunteers to join the team to help with these projects and more. As Owen mentioned last year, team member responsibilities include:

• Attending the IRC meetings
• Regularly spending time handling routine tasks
• Volunteering for infrastructure development projects as needed

We have a number of projects planned for this year, so that 3rd bullet is important!

If you are interested in joining the team, please join the gnome-infrastructure mailing list and introduce yourself, why you want to join and any relevant skills or experience you have. It is helpful if you have been active in other GNOME teams and can have someone vouch for you. (We are talking about giving you root access to GNOME servers, after all!)

If you have any questions, please feel free to send me an email, email the infrastructure list or stop by the #sysadmin IRC channel on GIMPNet IRC.