On Writing, Tech, and Other Loquacities

The collected works of Lana Brindley: writer, speaker, blogger


Leave a comment

Writing enterprise docs with an upstream. A life lesson in giving back.

The Eiffel Tower was erected for the Paris World’s Fair in 1889. Nobody much liked it though, and the plan was to let it stand for twenty years, and then tear the horrid thing down. But, here we are, over 100 years since its planned demise, and the Eiffel Tower has become a symbol of all things Parisian, the city of love. What saved it, in the end, was the invention of radio, when some smarty took one look at the the massive towering grid of steel, and thought Merde! Une antenne!

Like the Tower, in open source we rarely set out to achieve what we end up with. Sometimes, we set out not really having any idea what we want to achieve at all, and then we just spend the whole time rolling with the punches. Neither is necessarily bad; in open source, those approaches tend to work just as well as any other, most of the time. Where it becomes difficult, though, is when working on upstream becomes part of your job description. All of a sudden, you have to try and fit the square peg of open source into the round hole of your day job. So where you once had a process of “find something interesting, and then work on that”, you now have a process that involves planning, metrics, deliverables, and probably Gantt charts.

I knew about Linux fairly early on. I didn’t use it of course, I was a Business student, not some nerd. All of which meant I knew about Linux, but I didn’t understand it. Understanding came later, when I picked up an Information Systems major (much to the confusion of my non-nerdy friends, and still to the confusion of my parents). This was in the mid-nineties, so it was also around the time I discovered many new and exciting things: like IRC (a text-based chat system), the early years of Google (back when it was just a search engine), and open source. Some might say that my destiny was more or less set right from that point.

Fast forward a decade or so: I’ve gotten married, had a daughter, and somehow landed an office job at a startup that is only barely funding my MBA and my divorce proceedings. The CTO (employee #3) was an open source nutjob, and along with teaching me what a tech writer was (and blowing my mind in the process), he also managed to reignite that fascination with open source that I had first discovered during my undergrad. As far as I could tell, he achieved work by typing binary directly into the Linux kernel. And while I figured I’d never get to that level of wizardry, I was pretty proud of myself for learning LaTeX out of a book, and actually managing to produce useful technical documents for the company.

Sadly, like many startups, the dream didn’t last long, so when they missed my third paycheque in a row, I started looking for new opportunities, this time armed with a working knowledge of open source, and a desire to write documentation. After some tumbling around, I landed in Brisbane, Australia writing tech docs for Red Hat, rose into a management role, and was then offered a similar role at Rackspace about a year ago. So here I am, with nearly a decade of experience in working in enterprise-level open source documentation.

For those of you who haven’t been lurking on the edges of the open source world for the better part of a quarter of a century, open source tends to fall into two main categories: the single person project that starts as a simple solution to one problem and never really grows much past that, and the bigger more organised project that organisations start to notice. Projects like OpenStack, Libre Office, Inkscape, and Linux itself all fit into this category. When a company starts wanting to offer these products to their customers, they usually hire staff to work on an internal version of them that they can tailor to suit their needs. In this situation, the open source project is referred to as the ‘upstream’ or ‘community’ version, and the branded version produced by the company is referred to as the ‘downstream’ or ‘enterprise’ version.

However you fall in to this weird world of enterprise-level open source, it always starts out with that amazing feeling that someone is paying you to work on something you were perfectly willing to do for free. Eventually that wears off, though, and you find yourself in a place of competing deadlines, mismatched workflows, massive differences of scope, and oddball enterprise requirements. The first thing that will probably be apparent to you is that, despite wanting (or needing) to do more or less the same work on both your enterprise and upstream projects, you probably hold different roles in each group. You could be an entry-level programmer at your workplace, with a core role in upstream; or a manager at work, but a plebeian technical contributor in upstream. Even if you have relatively comparable levels of seniority in both, those roles will necessarily mean different things in each group. This is naturally going to lead to your first real issue:

How do I organise my time and achieve any kind of work/life balance?

Like many lists of hints and tips, this one also starts with the obvious: get organised. As soon as you know your enterprise release dates, let your community know that you won’t be around much during that time. Likewise, make sure your company knows when you’re busy with community work, too.

You won’t always have control over release schedules, especially in bigger projects, but if you do, try and stagger them. Having enterprise releases a set period of time (a month or more) after a community release can be a really good way to do this. This gives you time to take the community release and fiddle with any content that you need specifically for your enterprise customers, and also allows the community time to find and fix the bigger, more damaging, bugs.

Always prioritise your time and pick your battles. Don’t spend three days nursing a non-critical patch through the review process, or arguing over a minor technical point on a mailing list if you don’t have to. If you’re lucky enough to be in a management or senior community position, then delegation can also be helpful. Consider assigning a proxy to attend non-essential meetings or monitor mailing lists.

Finally, don’t fall into the trap of doing only enterprise work while you’re in the office and your boss is watching you, then doing all your community work at home after hours. That’s a recipe for burnout, regardless of how much you enjoy doing the community work. You still need to make sure you get time with your friends and family away from the computer, hit the gym occasionally, and get in some all-important couch time.

How can I be a good community member without looking like a company shill, *and* keep my job?

It’s natural to assume that there will sometimes be conflicts between what your company and your community wants. The best way to handle this is to have already created a culture of honesty and respect in both groups, but that is often beyond your control. Whatever the prevailing culture, though, you can always create your own reputation. Doing this right from the beginning will not only help you when trouble arises, but should also help influence the community’s culture too, even if it’s only in a small way. (If you’re interested in hearing more about creating culture in technical writing teams, come along to my presentation “8 writers in under 8 months: from zero to a docs team in no time flat” at linux.conf.au in Auckland, New Zealand 12-16 January, 2015. The talk should also be made available as a recording after the event)

To create your own reputation, start by being honest with both your company and the community. If you’re pushing a feature upstream because your company wants it, say so, and consider it a use case. If your company has customers wanting a feature then that’s a good reason to do it. If there aren’t any customers asking for the feature, though, question the real reason why it’s being requested, and don’t just pull rank and shove it through the upstream process because your boss told you to.

In order to keep your job, and to keep on being able to work on upstream, it’s important to make sure your company understands what you do in the community. It’s a good idea to have your upstream responsibilities enshrined in your job description, and reinforced at performance review time. If you can, make community contributions and achievements (lines of code, number of patches accepted, achieving more senior community roles) a performance goal. The other side of that coin is to make sure you’re actually doing it. Even if you’re super busy with an enterprise release, spend a little time every day on community work. Even if it’s just triaging a few bugs, or completing a code review or two over your morning coffee. It’ll help the community to not forget that you exist, and it’s a constant push of effort you can show your manager when you need to justify your existence.

How do I get the stuff in the enterprise version into upstream, and back again, without losing my mind?

This is obviously going to be different with every project and every company, but the main thing to do is to create a system. It could be tools based, or just a method of organisation. Perhaps keep a log of things that need to go up or down as you come across them, then check things off the list once they’re done. This is easily achievable with a Kanban board (either sticky notes on a wall or one of the many internet-based tools), and they’re especially useful if you’re working with a team.

It’s also important to be realistic. Don’t just take things upstream (or down) because you wrote them and you think they’re pretty neat. Make sure they’re valuable contributions that suit your stated use case. The audiences for enterprise and upstream will often be different, and different content will be required to satisfy each. That said, always be as fair as possible. Don’t be all take and no give, or vice versa. It’ll only erode your goodwill with the community, or make you That Guy at work. No one wants to be That Guy.

How can we make this better, and less painful? Won’t someone think of the yaks?

Until we’re all plugged mentally into the Internet of Things, and all thought becomes networked, this is likely to remain a difficult problem to solve. Every community and every organisation is different, sometimes radically so, which means trying to get two to work together can be like picking two random cogs and hoping they fit. Sometimes, miraculously, they do, and sometimes there’s just a grinding of gears. Often, though, they fit imperfectly, and those are the ones we can work with.

It’s important that enterprise and upstream are as aligned as possible, and that the organisation has an understanding of upstream concerns. This can often depend on whether your organisation was grown with open source as a core consideration from the beginning, or they only decided to go into upstream later on, as it will massively impact the prevailing company culture.

That said, even a company that decided to work with open source last Wednesday can be taught how to be a good corporate open source citizen. Firstly, the more people working on upstream within your organisation, the better the organisation will get at it. You also want to avoid being the single touch point between your company and upstream. If your company is hiring, make sure you spread the word around your community, and if you find someone looking for work in your community that would suit your organisation, make a case to get them hired. You also want to make sure that you talk about open source with your management team as much as possible. The more your manager understands, the better able they will be to talk about open source to their manager, and so on up the chain of command. If, one day, the CEO declares an open source strategy, then you know you’ll have gotten somewhere.

Finally, don’t be disheartened if you sometimes feel like you’re working two full-time jobs, fighting fires in one and saving drowning kittens in the other. Take a holiday, and when you’re refreshed look at your processes again. If you can take a step back from the trees, you’ll see the forest more clearly and work out the little things you can implement or change to make your life just a little bit easier. Don’t give up, the open source world needs all the corporate advocates they can get, and with your help both your company and your community will be better off in the long run.


This article is the text version of a presentation of the same name to be delivered by Lana Brindley and Anne Gentle at the OpenStack Summit in Paris, France on 3 November, 2014. The talk should also be made available as a recording after the event. It first appeared in article form in the Society of Technical Communicator’s publication Southern Communicator.


Leave a comment

Gym memberships and Dental Hygiene

Why must exercise and fitness carry with it a “goal”? We must we be “losing weight”, “gaining muscle”, “in training”,  “getting fit”, or any one of a myriad other things. Why can’t I just do stuff that’s fun, and fits my lifestyle because, well, it’s fun and fits my lifestyle?

tenpoint-advertising-1-fitness-first-1

What if I am happy with the me I have all year round?

I absolutely loathe the procedure that you have to go through in order to sign up to a gym or other organised fitness group, or to start seeing a new personal trainer. First of all, you have to make an appointment. Then, you have some kind of “fitness consultation” where some impossibly skinny twelve year old weighs you, measures you and then adds all those numbers together. This is so they can “measure” your “progress” towards your “results” . Believe me, I’ve tried joining up to gyms with the line “actually, I don’t have a goal. I just want to come and work out a few times a week”. First of all they look at you like you just grew an extra elbow on your forehead. Then they jot down “weight loss”, because that’s what everyone wants in 2014. After that ritual humiliation, you’re then expected to sign up for all the “extra” “services” they “provide” (personal training, saunas, small group training, large group training, the list is endless and none of them are included in your membership fees. And that’s another whole rant). Then, three months later, when you haven’t achieved the imaginary goal you made up to satisfy them when you joined, the REASON you haven’t reached it is OBVIOUSLY because you need more personal training. Or bootcamps. Or something.

I would like to treat exercise in the same way we treat dental hygiene. I brush my teeth twice a day because I don’t want my teeth to rot and fall out. I go to the gym four times a week because I want to be able to eat cake occasionally, and hopefully still be walking around when I’m 80. What I don’t want is to be forced into setting a “goal” that I am likely to forget within my first two visits in order to sign up.

I don't need to set a dental hygiene goal to know that I should brush my teeth.

I don’t need to set a dental hygiene goal to know that I should brush my teeth.

 

So, while I firmly believe the “obesity crisis” is pretty much a beat-up, if you want to get people moving more and attending gyms, stop making them out to be something so freaking special, and encourage us to think of it as just something that humans living in the world do. I don’t need to set a goal for myself to brush my teeth, buy vegies when I go grocery shopping, or hug my daughter. Why should I set a goal to incorporate exercise into my life? I’m doing this for the long haul, not just until I’ve lost a couple of kilos.

When your goal is “still be here at 80″, fast-tracking seems awkward.


Leave a comment

The only writing sample you need is your resume

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.

shakespeare

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!


Leave a comment

OpenStack at linux.conf.au

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

11846594876 3d35cfd16f b.jpg

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.

11855948834 bce9a4d1fd b.jpg

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):

Continuous Integration for your database migrations by Michael Still

Rapid OpenStack Deployment for Novices and Experts Alike by Florian Haas

How OpenStack Improves Code Quality with Project Gating and Zuul by James Blair

Diskimage-builder: deep dive into a ‘machine compiler’ by Robert Collins

Processing Continuous Integration Log Events for Great Good by Clark Boylan

Provisioning Bare Metal with OpenStack by Devananda van der Veen

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.

IMAG0119.jpg

Watch the talks mentioned in this blog post:


Leave a comment

linux.conf.au and the OpenStack Miniconference

linux.conf.au doesn’t start until Wednesday, but that didn’t stop an eager group of Rackspace engineers rocking up on Sunday night.
11846078833_225150858c_bWe 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.
11845810725_912f311b84_bThis 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.
11846082123_8be3ce7822_bAnd now that the miniconf is done, it’s time to get the conference started! Stay tuned for another post about linux.conf.au.


Leave a comment

Birthdays, and Other Silliness

I woke up on the morning of my birthday to this, at the top of our team wiki page:

Lana_birthday

Admittedly, this isn’t the silliest thing we’ve had at the top of our wiki page recently. In fact, our manager Mikal has made it a work requirement that we create at least two new memes a day, as a team, and a script rotates them on a daily basis.

The point of mentioning this is that I wanted to talk a little about our culture. We’re a small team, and we’re the only Rackspace engineering team within Australia, which makes us fairly unique. Of the four of us, we’re scattered quite neatly along the Australian eastern seaboard, in Canberra, Adelaide, Hobart, and me in Brisbane. We’re very new as well, so for the moment we’re basically muddling our way through. However, there are grand plans, some of which don’t even include crowning Mikal as the Sarcastic God of All Pickles, as hard as that may be to believe.

The main thing we want to try and achieve, at least to begin with, is to create an identity for the group. Mikal and I have worked on this kind of thing before (albeit with a shorter lifespan), with linux.conf.au 2013. With the conference, we spent a lot of time working out what the ‘feel’ of the conference was going to be, and what our messaging around that should be, how we should convey that feeling to the audience.

My very next step in doing the same thing for the Rackspace Cloud Builders Australia group is exactly the same as we did for linux.conf.au 2013: work out the over-arching message, and then decide on ways to effectively communicate that. We need to work out how to be fun and energetic, without compromising the message that we are smart and innovative, and working hard for our customers. A brand challenge to rise to.

Have you ever crafted a similar message for a group you’ve worked on? Do you have advice for me?


Leave a comment

OpenStack Contributions

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.

Stackalytics_firstcommit

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!


Leave a comment

An exit, and an entrance

All the world’s a stage,
And all the men and women merely players:
They have their exits and their entrances;
And one man in his time plays many parts
— ‘As You Like It’, Shakespeare

It is not often that you have to make a choice between an amazing job, and another amazing job. But, after six years with Red Hat, I have decided to take up a new position with Rackspace, effective 28 October.

I have grown up with Red Hat, in particular the Australian writing team, and in many ways the person I am today has been shaped by the people and the culture here in the Brisbane office. I am sad to be leaving, but I take a little piece of that crimson fedora with me. To all my friends and colleagues at Red Hat: keep up the great work, keep innovating, and know that there are Red Hat alumni out there, cheering you on from the sidelines.

To anyone who is considering embarking on a technical writing career, or expanding their tech writing horizons, consider joining the team at Red Hat. They’re doing groundbreaking work, they’re doing it out in the open, and they’re having a huge amount of fun as they do it.

I’ll be blogging a lot more in my new role, so please stay tuned as this site gets a bit of a nip and a tuck, and before long you’ll start seeing a lot more from me.

the-weird-writer


Leave a comment

Linux.conf.au 2014 – Perth, WA

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!

linux.conf.au 2014 - Perth WA