Leading a community group, it turns out, is completely different to being a manager. I learned this the hard way; I made mistakes, started (and continued) arguments, and sometimes, when faced with a large hole, simply continued to dig.

In late 2014 I had been working on OpenStack documentation for about a year. We were preparing the Kilo release, when the current project team lead (PTL) asked if I would be willing to put my name forward as a candidate for Liberty PTL. In early 2015, I was elected unopposed to lead the documentation team for the Liberty release, and all of a sudden I realised: I had no idea how to run a community group.

At this point, I had managed docs teams of various sizes, across many timezones, for five years. I had a business management degree and an MBA to my name, had run my own business, seen a tech startup fail and a new corporate docs team flourish. I felt as though I understood what being a manager was all about. And I guess I did. But I didn’t know what being a PTL was all about. All of a sudden, I had a team where I couldn’t name each individual, couldn’t rely on any one person to come to work on any given day, couldn’t delegate tasks with any authority and couldn’t compensate team members for good work. The only tool I had in my arsenal to get work done was my own ability to convince people that they should.

If you’ve spent time as a manager in a corporate environment, you’ll be used to keeping secrets, actively managing your employees’ careers, and pretending you know the answers to things (especially if you don’t). This is entirely the wrong way to go about managing a community, and if your team decides you’re treating them like that, they will probably only give you a couple of chances before they eat you alive1. If you get it right (even if it’s on the second go-round), the opportunities for growth and satisfaction are unbeatable. Not to mention the sense of achievement!

My first release as a PTL was basically me stumbling around in the dark and poking at the things I encountered. I relied heavily on the expertise of the existing members of the group to work out what needed to be done, and I gradually started to learn that the key to getting things done was not just to talk and delegate, but to listen and collaborate. I had to not only tell people what to do, but also convince them that it was a good idea, help them to see it through, and pick up the pieces if they didn’t. You will end up stumbling around in front of your team a lot in open source. Here’s how to make it work for you:

Rewarding the good, punishing the bad

The phrase ‘carrots and sticks’ is often used to describe the process of rewarding good behaviour (carrots)2 while punishing bad behavior (sticks)3. Rewards are everywhere in today’s corporations. From monetary incentives (bonuses, share schemes, gift cards and shopping vouchers), to various team activities (lunches, dinners, paintball, barista courses, and all manner of competitive activities), these awards are designed to make all your colleagues envy and despise you. Not to mention all those little branded tchotchkes (a stress ball in every imaginable shape!) we all seem to accumulate. There are so many carrots given out, that not getting any can often be a form of stick.

Of course, this is the first and most obvious thing you will notice missing when you start managing a community rather than a team in an organisation. You don’t get to pay them. You don’t get to give bonuses. And the tchotchkes are harder to find and more jealously guarded.

The first thing you have to do is work out what you have got. Got access to stickers, t-shirts, or other branded merchandise? Give them out! What about privileges (and no, giving someone more responsibility is not a privilege, so don’t count things like granting core access)? Things like discounted tickets or travel to conferences, access to company-sponsored events like code sprints or meetups, or things like the ability to vote on leadership positions can all be considered perks of being part of a community.

There are also other, less obvious, things that you can do to motivate people: always be willing to call out great work (or even mediocre work, especially if it came from someone surprising) in a public way, but keep any criticism private. Thank people, a lot, for everything. Make sure when people email you asking questions you add other people into the conversation, with a note like “this person is an expert on this topic, and I’d love to hear their opinion”. Flattery and thankfulness are some of the best tools you have to motivate people on your team, and they’re entirely free. Just try and keep your ego in check and let other people take credit wherever possible.

Performance measurement as a behaviour management tool

One of the more popular performance measurement methods is referred to as a nine box, or a talent matrix4. The idea of ranking employees can be quite distasteful, so it’s important to remember that it’s not about ranking staff against each other, but against themselves and their own past performance. You should be able to see each employee move from the lower left to the top right of the matrix as they improve in their role. Once they hit the top right box, you must be ready to promote them, at which point they drop to the centre of the matrix, and start the journey up and to the right again. Of course, the opposite is also true: if an employee starts to track down and to the left, you need to be having some serious discussions about the role that the person is in, whether or not they’re having personal issues, or whether they’re the right fit for your team, or your company. The point is, there’s something of a science to this when you’re in a corporate environment.

That science becomes much more of a dark art when you’re leading a community. For starters, though, you need to remember that it’s not really your responsibility. Most of the people in the your community already have a job, and a career path, and a manager who (hopefully) cares about those things. And that person isn’t you. Also, those things are (and should be) fairly opaque to you, it’s really none of your business. But that doesn’t mean that you shouldn’t care about your team’s performance within the constraints of your group. Most communities have levels of responsibility within them. From leading sub-teams, to being involved in testing, sitting on advisory boards, or becoming core contributors with greater levels of trust and expectation, right up to leading the group itself, you need to be aware of the aspirations of your community members, and ensure you’re letting people know the options available to them should they wish to progress. An extra added complication is where these two things intersect. You never know if a team member is getting pressure from their corporate manager to achieve a certain role within your community, or what value (if any) companies might place on metrics, roles, or positions of trust within your community. You can’t always rely on team members to tell you what they’re trying to achieve, either, sometimes they make you guess.

The best way to ensure you’re helping individuals succeed in their performance goals is to make sure you understand what those goals are. This isn’t always easy and you can’t necessarily assume that all team members want to progress, either. This is even more true in communities than in companies, since a promotion often means more responsibility without any increase in benefits (you’re not paying them, after all). The best way to do this is to ask people, and the best way to get a good answer is to do in private. Don’t be afraid, as a community leader, to reach out to people directly, saying something along the lines of ‘hey, I noticed you’re doing great work, and wanted to have a chat to you about the kinds of things you’re interested in working on, and how I can help you achieve your goals within our community.’ You won’t always get all the answers you might want, in the detail you might need to really help them, but at least you’ll have a better idea than just assuming everyone wants to become a team leader some day.

The performance art of trust

Perhaps more important than rewarding staff, or accurately recording their performance improvements, is proving that you trust them. A little trust goes a long way and can positively impact loyalty, morale and retention. As a manager, there are many occasions where you are privy to information you can’t share with staff: financial or company performance information, restructures, or even layoffs. The thing is, your team members are probably pretty smart and they probably know that this is a thing. You need to reassure them that as soon as you can tell them, you will. But there’s more to it than that; there’s something I like to call the performance art of trust, which is more about telling them when you don’t know something than when you do. If someone asks you a question, and you don’t know the answer, don’t make things up! Just come right out and say it: “I don’t know.” You might find it helpful to practice, because it’s not easy to do when you’re trying to be all manager-y and stuff. In fact, most of your training to become a manager has probably been about pretending you know the answers when you don’t, which is exactly the wrong way to go about it.

Of course, as a community leader, you almost never have access to information before anyone else, so you may be wondering why this is relevant. It’s because the principles of honesty and trust are just as important, if not more so, in community situations than they are in a workplace. Community members will work with you if they want to work with you, and they won’t work with you if you’re a twit. The best way to look like you’re someone worth working with is if you appear open, honest, communicative, trustworthy, and reasonable.

One of the hallmarks of many open-source communities is the somewhat impassioned email communications5 that occur. Flamewars on mailing lists are a feature6 of open source communities and they happen out in public. Treat them as performance art, where your audience is focused on one thing: is this person someone I trust to lead this group?

It’s easy to come out of a flamewar looking like a buffoon, so here’s a couple of tips:

Always read the email you’re replying to thoroughly, several times, and try to understand the sender’s point of view. Work out what the question is (if there isn’t a question, then don’t send a reply).

Start your reply by thanking the sender: for bringing up a point you hadn’t considered, for asking questions, or even just for taking the time to put their thoughts into words. This forces you to assume good intent.

Answer the question, AND ONLY THE QUESTION. Give reasons for your answer, using dot points if necessary, but don’t bring other issues into it, and certainly don’t launch into personal attacks. Be prepared to question your own beliefs about things (you don’t have to change your mind, but you need to be open to other perspectives).

Ask a question of your own: Do they think this is reasonable? Can they think of something you might have missed? Do they have further comments?

Don’t hit send yet. Leave it as long as possible; at least a couple of hours, preferably overnight. This not only gives you time to calm down a little, but it also slows down the exchange on the mailing list, which will hopefully remove some heat.

Before you hit send, proofread, and take out all the emotional language. Work out if you can consolidate some points, reorganise the content to be clearer, or take out irrelevant information. Be as concise and to-the-point as possible.

If the thread has been dragging on and there’s no progress, take it offline. Admit that perhaps you don’t fully understand their viewpoint and offer a video or phone call, even if it’s an early morning or late night for you. Be the bigger person, take the hit. People are always much nicer on the phone, and if nothing else, it stops the flamewar.

To conclude, communities are definitely more forgiving than corporations, so you’ll probably get away with stumbling around a little bit before you find your feet. However, they’re also run almost entirely on trust and goodwill and you can erode that really quickly and sometimes without noticing. Be honest when you don’t know something, own up to your mistakes, never shift blame (even if you really didn’t do it), and always lift your team members up. If you can nail those things, then you’ll find a way through, and I’m willing to bet that you’ll become a better manager in the process as well.

1. OK, maybe not actually eat you, but they won’t like you for it. Not even a little bit.?2. Why anyone would continue a good behavior for a carrot reward, unless they were a bunny, is beyond me (I prefer chocolate biscuits, personally), but it’s as good a shorthand as any to describe this process.?3. Please don’t actually beat anyone with a stick. It’s poor form.?4. The nine box performance matrix is usually attributed to McKinsey, who invented it in the 1970s for GE. If you’ve done any classes at business school, you’ve probably done a course on it. For the purposes of this article, however, it is simply a method of plotting team members on a graph from lowest performing in the lower left, to highest performing in the upper right. Most nine box models plot performance on the x-axis, and behaviour on the y-axis, but there are many variations.?5. Some would call them ‘flamewars’.?6. Some would call them a ‘bug’.?

This Summit was a homecoming of sorts. OpenStack started in Austin with 750 people, and returned six years and twelve conferences later with 7500 people. Even the baristas in the downtown coffee shops noticed us the second time around.

For documentation, this conference was bigger than usual as well. We had a total of eight sessions, in addition to the contributor meetup on the last day, which is more docs sessions than we have ever had before.

And we had a lot to talk about! The biggest thing on our minds was the future of the OpenStack Installation Guide. The Big Tent has changed the way that projects go about joining the OpenStack ecosystem, and with Foundation having an increased focus on ensuring new projects have sufficient documentation, we needed to change our approach to documenting the installation of an OpenStack cloud. There is no ‘right’ way to install a cloud any more, and there is certainly no ‘right’ set of components you should be installing when you do it. But with a small documentation team, and a seemingly endless parade of new components requiring documentation, we were faced with a big technical challenge, where everyone had some kind of skin in the game. Despite some differences of opinion, the session itself was extremely productive, and we came away with a solid set of deliverables for Newton. First of all, we’re going to create the infrastructure to allow projects to write their own installation docs in their repos, and then publish them seamlessly to the docs.openstack.org front page. This means that projects have responsibility for their own docs, but the docs team will provide assistance in the form of templates and infrastructure support to ensure that all projects are treated as first class citizens. Secondly, the existing Installation Guide will change focus to be more about an installation tutorial, giving people a highly opinionated and completely manual installation method to learn the ropes, but not to install a production cloud. Thanks to the OpenStack User Survey, we can safely say that most production clouds are installed using some kind of automated tool, so having manual installation instructions is useful as a training tool, but not in a real world scenario.

With the big question more or less settled, we got on to the fairly long laundry list of other things that needed to be done, which all ended up focusing mostly on streamlining some of our processes, being clearer about the way we operate, consolidating guides that had (for obscure historical reasons) been in their own repos into the main one again, and general editing and tidying up. A full list of the goals can be seen here: Newton Docs Deliverables. And, for historical interest, here’s the whiteboard from the Summit session:

During the Mitaka release, docs had a focus on Manageability, aiming to work more effectively and efficiently, with a focus on collaboration. For Newton, while manageability themes are still very much present, the focus is more on Scalability, and making our documentation efforts scale out to represent a much greater proportion of products, contributors, operators, and users. From empowering projects to write their own documentation with our support, to making our processes simpler to find and understand, to ensuring our documentation is as accurate, up-to-date, and effective as possible, it’s going to be an exciting cycle for docs!

I leave you with one of my favourite Texan big things: a bathtub margarita!

Day 1 is drawing to a close at linux.conf.au 2015 and we’ve just wrapped the documentation miniconf. There was an interesting mix of talks today, and as the first documentation miniconf at an LCA, it’s given me some great ideas for growing the miniconf in future years.

As for me, after doing the Agile Documentation Lego talk at LCA in Perth in 2014, I felt I needed to give a good follow up show, this time focusing on Every Page is Page One. To do this, I devised a game based on the children’s book “We’re Going on a Bear Hunt”, and using Play-Doh to make it a little more hands on.

I came across this article recently, which states “code is the new resume”. It asserts that people seeking coding jobs should be contributing to open source and using those contributions as proof that they have the skills for the job they’re seeking. I wholly agree, but it got me thinking about the equivalent for writers.

When I have had prospective tech writers come to me for advice on where to start, I have always pointed them towards an open source project that I think would meet their skills and interests. I usually have three main reasons for this. I want them to get experience working with processes within a docs team (particularly a mature docs team that functions well, such as Libre Office or OpenStack). I want to give them an opportunity to get familiar with the tools and programs used by highly technical writing projects (things like Docbook XML and Publican, rather than proprietary tools like Madcap or Adobe). And, perhaps most importantly, I want to give them a chance to write things that they can share with prospective employers.

But contributing to open source docs, while beneficial in career terms, rarely ends up being something you can confidently wave in front of an employer. Rarely, if ever, will you get the chance to create a new document from scratch, something you can call truly yours. And even if you get that chance, rarely will it remain the piece of art you crafted for very long. Open source software moves quickly, and by the time you publish your meticulously researched and effectively written document, there will be a team of hungry writers circling, ready to rip into your virgin words and tear them apart. Within months, your perfect book could be an almost unrecognisable crime against information architecture, full of passive voice and typoed commands, with a title that no longer reflects its content. Certainly not something you want your name anywhere near.

Herein lies the tech writer’s dilemma: when asked for writing samples, what do you do? You don’t want to admit to authorship of something that (through no fault of your own) makes you want to quit the industry, but you also don’t want to say that you’ve been contributing to a project for months and have nothing to show for it. My answer: make your resume your writing sample. You won’t always get away with it, because some employers will ask for writing samples as a matter of course (at which point, having kept a tech writing blog for a while can be very handy. Just sayin’), but having plenty of prose in your resume and making sure it shows off your skills will do wonders for proving you can do the job.

There are no rules saying you need to deliver a two page resume, developed using a standard Word template, to apply for a job. Designers have been handing in creative resumes for decades, and we can take a leaf out their book. Offering something different, something that screams “I’m a writer, and I’m damn good at what I do” is going to make any recruiter or hiring manager stop and look. Remember how many resumes these guys see. Offering a bog-standard resume means that yours will get thrown away at the first typo.

First of all, do your research. If you can, find out what writing tools your prospective employer uses, and use it. If you don’t have that in your repertoire, then use the closest thing you can do. When I applied for my first job that used Docbook XML, I delivered my resume in LaTeX (complete with “Typeset in LaTeX and TeX” in a footnote at the bottom of each page. Nothing like rubbing it right in). I later found out that the hiring manager ran around the office showing it off to all his existing writers, pointing excitedly to the footnote. Once I’d learned Docbook XML, following jobs got that instead. If the company you want to work for uses Word, then deliver a beautifully formatted Word resume (and don’t forget to use styles!). By the same token, be aware of internal culture, and the fact that people get very passionate about their tools. Never deliver a resume built in Word with a .docx extension to an open source company if you don’t want to be teased about it forever after (assuming you get the job despite it, of course).

And, perhaps most importantly, don’t just deliver a series of dot points. This is your chance to prove you can write. Include a fairly long prose introduction, but don’t waffle. Be clear about your goals, the job you’re after, and any relevant work you’ve done previously. If you can, do some research into the company you’re looking to join, and tailor this part to the role you want. Mention how your experience meets their demands, not as a canned response to selection criteria, but as someone who has gone looking for core values and culture clues, and is addressing the human beings that work within that group. Write directly, succinctly, but passionately. Don’t use words too big for the subject (with apologies for paraphrasing C.S. Lewis), make your language casual, but not informal. Get your writer friends to proofread it until you are confident it is perfect. Feel free to email me with your text and I’ll also help.

Don’t make recruiters ask for writing samples. Get creative, use your skills to your advantage, and don’t be afraid to have some fun with it. If you have your own stories of resumes (good or bad), or hiring, please share!

linux.conf.au this year is being held on the beautiful University of Western Australia campus, in Perth.

About 500 geeks have descended on the campus, with talks being organised into six topic streams across three days. The conference is entirely volunteer-run, with financial and community support from Linux Australia. The conference is designed by and for developers, with an emphasis on deeply technical talks. Of course, it’s not all code, though. An important aspect of open source technology is the community, and usually one track at linux.conf.au is dedicated to community matters such as diversity, governance, and documentation.

Every year, the conference schedule belies a popular trend in open source tech. This year, that trend has definitely been OpenStack, with many talks discussing various aspects of the project including continuous integration, bare metal provisioning, and deployment. Some of the highlights (to watch video of these talks, see the links at the end of this post):

One of the most important and interesting aspects of OpenStack is its ability to link in with other projects to extend and expand its use. The conference has been a great opportunity for developers to work out how they can use OpenStack to help their own projects. Rackspace also helped encourage this by offering developers at the conference free access to the Rackspace cloud for OpenStack developers.

Of course, sometimes it’s not just the formal talks at a conference that are the best part. Sometimes it’s all about meeting a new person who might be able to help you out with that sticky problem, or catching up with old friends and having the opportunity to just geek out for a little while over a nice meal and maybe a drink or two.

linux.conf.au doesn’t start until Wednesday, but that didn’t stop an eager group of Rackspace engineers rocking up on Sunday night.We didn’t just sit around in empty conference rooms, though. Michael Still (he’s a Nova core and manages a team of OpenStack engineers in Australia), ran an OpenStack miniconference, which is an informal, day-long session before the formal conference opening. We heard from people from all over the OpenStack universe, including HP, Catalyst, Canonical, and IBM, and the topics of conversation hit upon all aspects of the project. For a full list of the speakers and topics, head along to the miniconf site.
The general idea of this informal start to the conference is to give like-minded people a chance to get together and discuss things that are important to them before the formal conference sessions begin. The miniconfs also act as an incubator of sorts, to be able to foster and encourage people who might be interested in a topic to dip their toes further into the water. The OpenStack miniconf in particular gave people an opportunity to learn about OpenStack development, help them to understand the state of the nation of OpenStack and what things they might be able to help with, and to provide a bunch of knowledgeable people for them to ask questions of.This is Michael talking to Anita Kuno, an OpenStack developer from HP, who discussed support services for OpenStack developers during the miniconf.
Of course, the other really awesome thing about the miniconf is that gave a chance for OpenStack developers to get together in person. People who have chatted and argued on a mailing list or in code reviews during the year can often find common ground over a quick chat in between sessions, or during a Q&A session.And now that the miniconf is done, it’s time to get the conference started! Stay tuned for another post about linux.conf.au.

Like most people I learn best by doing, so one of the first tasks I set myself when I started working on OpenStack documentation was to get a docs patch in as quickly as possible. In the end, this turned out to be a copyedit on the introduction to the High Availability guide, and it happened on day two, right before I did my induction in Sydney on day three. I had no idea this was a big deal until I got to the Sydney office to find myself being lauded, which was somewhat amusing, and slightly embarrassing.

So the main upside of this is that I am now officially an OpenStack ATC (active technical contributor). The next step from here is to keep making patches of course, along with code reviews and the like and hopefully to continue being useful to the community in this way.

One of the more important things about coming to a new project is working out the workflows. All the formal stuff is documented, of course, but sometimes it’s the common knowledge things that are hardest to pick up; the bits that ‘everyone knows’. I’m still feeling a little daunted by code reviews (what exactly constitutes an acceptable patch? To what extent should I be testing the proposed content?), but after discussions with the core docs contributors I’m starting to get a handle on those. This week has been spent largely as a sponge: just trying to soak everything up. After a day or two off over the weekend, hopefully my brain has made sense of most of the things I’ve learned so far, and next week will be a week of action!

Possibly my favourite conference, linux.conf.au is coming to sunny Perth in January 2014. I’ll be returning to the Haecksen miniconf driver’s seat (check out haecksen.net for more info and the Call for Proposals), and also will be giving a talk myself, called There and Back Again: An Unexpected Journey in Agile Documentation. This is a talk I’ve given a few times already, including at OSDC 2013, so I’m really looking forward to sharing it with the linux.conf.au audience. That, and I’ve never been to Perth before, so yay!

OSDC 2011 kicked off today at the ANU. I tripped along to the OSIA (Open Source Industry Australia) miniconf, which Red Hat sponsored, and was mightily pleased to hear Stuart Gutherie reference one of my favourite pieces of historical weirdness: the mechanical turk. I couldn’t help but hold forth, and eventually gave an impromptu lightning talk on the subject.

The mechanical turk existed in the late 1700’s, and was billed as an “automaton chess player”. In reality, it was a wooden box in which an accomplished chess player could sit and manipulate the chess board on top, while a wooden “turk” would appear to move the pieces mechanically. It was invented by Wolfgang von Kempelen, a Hungarian, who also invented a “speaking machine”, a speech synthesiser, which was actually quite important to the early development of phonetics as an area of study, but not half as famous as his great hoax, the mechanical turk.

What makes the mechanical turk so interesting is the lengths von Kempelen went to to persuade his audience that the turk was, indeed, an automaton. He would show the audience first one empty cabinet, then another, and then in the third cabinet would be a complicated looking system of levers and pulleys. The cabinet was designed that, throughout this proceeding, the human operator could easily slip from one side to the other on a sliding seat to hide from view.

The trick was not exposed until the mid-1820’s, despite some very public appearances. The mechanical turk won chess games against such prominent figures as Napoleon Bonaparte and Benjamin Franklin before being found out, although no one has recorded the names of those chess players working the turk from underneath.

How this becomes relevant to the IT industry is equally as fascinating as the history of the machine. In the days of the turk, playing chess was something that no machine was capable of doing. It required a level of computation that only humans were capable of achieving. We have now invented computers that can play chess (and even appear on game shows) with ease, but there are still tasks that we can’t replace with a small shell script. Many of these tasks are frustratingly simple, but require a human brain to parse the data. Writing tasks often fit into this category: things like writing short captions for images, changing the style used in a document, or changing text from British English to American English spelling.

Within Red Hat, we spend a lot of our time working on errata text. After a program has been released it is fairly normal to find bugs. When the developers go through and fix a bunch of those bugs, they will send out an update termed an “errata release”. For each bug fixed, the technical writers need to document it, which means writing four sentences: one sentence each about the cause of the bug, the consequence of the bug, the fix that was applied, and the result of the fix. This is, naturally, quite tedious and boring. It’s natural for us to want to automate this process, but unfortunately it’s a job that requires a human brain.

So we did the next best thing: we created a mechanical turk. We call it “The Turkinator”, and it’s currently available for Fedora errata releases. Basically, you choose whether you want to write a Cause, a Consequence, a Fix, or a Result; you’re given a bug to read; you submit your sentence and that’s it. In this way, we automate the task of writing errata text by breaking the big task down into little tiny pieces and asking humans to perform the work of a shell script.

This model has an extra added bonus in the open source space, though, and that is what we like to call “micro-contributions”. Anyone who has contributed — or thought about contributing — to an open source project would understand how daunting that first contribution can be. By creating the possibility of micro-contributions, potential contributors can have their first (and second, and third …) patch completed in under a minute. Instant contributors for the project, and instant contributions for the development team.

linux.conf.au is the biggest Linux and open source conference in the southern hemisphere, and rightfully so! I was a speaker at the conference last year in Brisbane (the video is on my videos page) and had a great time.

This year it’s being held in Ballarat, Victoria, and I must say I’m quite looking forward to finding out what a regional LCA is like. Anyway, the CFP is open, I’ll be submitting again, and I suggest you do too. More details on the LCA website.

Where the bloody hell are ya?!

Who wrote all this stuff?

All writing on this blog is the work of Lana Brindley and does not necessarily reflect the view of Rackspace, OpenStack, or any other group with which I am affiliated, except where I have used direct quotes (which are attributed to the original authors where possible). All images were either taken by me, shared under their individual licencing requirements, or obtained as stock photography.