Writing

Introducing: Documentation strategy

Re-posted from Status.net.

No wait, don't leave! Documentation isn't boring! I promise! Hi, I'm Emma Jane Hogbin (@emmajanedotnet) and I'll be your Documentation Strategist (and tech author) for the 1.0 release of StatusNet. You may know me from such projects as the Drupal Documentation Team, the Bazaar version control system, Writing Open Source (the very first-ever open source documentation conference) and the Linux Documentation Project. I'm absolutely thrilled to be working with StatusNet.

Just in case you missed my talk at the Ontario GNU Linux Fest (video and slides) this fall, here's the plan: we're going to design our documentation to be usable, maintainable and translatable from day one. (We even have a plan.) We're putting developer documentation where developers need it; and user documentation where real people need help. Think of it as the "whistle while you work" approach. But it gets even better: the documentation will be reviewed per major release cycle to find areas where the code needs to be improved. The wiki edits to the documentation will be the canary in the coal mine for the StatusNet experience.

Most normal people think of writing documentation as being necessary, but not fun. Fortunately I'm one of those do-less-work kinds of people. I'm not into writing tomes of information that no one will read. I want only the Ikea instruction drawings in places where people actually need help. Here's where I need your help: whether you're a beginner, or a pro, I need to know the times when the StatusNet experience could have been made easier if we'd slipped in some instructions. We got the ball rolling at StatusCampMontreal and here's how it worked: Tell me, in less than 140 characters, what the pain points are (or were) for you. If you're on Identi.ca, tag your notices with #painpoints. If you want to add a little more detail, please add your pain points to the wiki, or drop me an email (emma@status.net).

I'm looking forward to uncovering some of your blisters and making the user experience even better in StatusNet 1.0.

Printed greeting card summary

Every now and then it's much easier to pay a little more for convenience. This week it was greeting cards on the list of things that I needed urgently. I initially thought that I'd take a PDF to one of the local print shops and have them create the cards for me. I spent a lot of time messing around with various MS Word and Photoshop templates ultimately didn't trust that what I'd produced was what a printer would need. I looked for an Avery template for cards, but none seemed to be quite what I wanted. I didn't have time to get a proof to ensure my templates were right. (I briefly wished that I had MS Publisher--which I know does exactly this kind of thing very well.) So I opted for an online service that would allow me to upload individual images for each part of the card (instead of making print-ready PDF artwork with crop marks). The process of finding a printer took as much time as I'd spent on the templates. And then it took me as much time again to test each of the three services I found to see if they'd do what I wanted. Hours and hours and hours of time. Not "wasted" but not necessarily efficiently used either.

HOWTO: Create an award for girls in tech

With yet another fail at an open source conference, I wanted to spend a few minutes to tell you about something that took me 20 minutes and will, I think, have a real impact on the life of one girl.

This week I started an award at my former high school for a senior female student that has demonstrated creative use of technology. She doesn't need to have the best marks, she doesn't need to have sustained performance. She just needs to have shown a sliver of inspiration and interest in technology to be rewarded and encouraged. In the game of Alice's Restaurant and World Domination, you have to start by doing one thing different. Here's the FAQ on why I did it and how you can start your own award too.

Note: "female" is intended to be inclusive of anyone who self-identifies as a girl or young woman. Unfortunately awards generally use the sex term, not the gender term. This HOWTO reflects that terminology.

Git for Teams

Git For Teams

Best selling title from O'Reilly media. Covers essential skills needed to use Git in a team environment.

Available from O'Reilly media, and better bookstores worldwide.

Collaborating with Git

Collaborating with Git

Practical how-to videos to get you, and your team, up and running with Git. A complementary video series for the book, Git for Teams.

Available from O'Reilly media.

Drupal User's Guide

Drupal User's Guide

Site building for Drupal 7. Includes in-depth information on Drupal's most popular site building modules, SEO and accessibility. Two complete case studies are included in the book along with the tools you'll need to build (almost) any Web site with Drupal.

Available from Amazon.com.

Front End Drupal

Front End Drupal

The industry go-to for learning theming in Drupal 6. A great companion to Lullabot's book, Using Drupal.

Available from Amazon.com.