On Writing, Tech, and Other Loquacities

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

Leave a comment

OpenStack Mitaka Summit – Docs Wrapup

Tokyo is a city that is all about contrast. From the neon lights of Shibuya and Akihabara (“Electronics Town”), to the shrines and temples dotted in green spaces around the city, old and new Japan come together in Tokyo in a surprisingly harmonious way. While OpenStack Summit, like the people of Tokyo, is focused on new technology and moving into the future, it is important to note the atmosphere of community, fellowship, and camaraderie that underpins the conference.


I am privileged enough to be the documentation PTL for Mitaka, having taken over the reins from Anne Gentle after the Kilo cycle. This time around, we have three main priorities to achieve, and I think it’s a  lovely blend between the technical and the community.

First of all, we will focus on improving the usability of our documentation, making it easier to navigate the docs site and find relevant information quickly. The main way we want to address this is through a different model of data typing, and moving away from a role-based architecture towards a task-based one. This is easier to do for some guides than others, of course, and we intend to start with the user guides. The other component of this is reorganising the index page, and adding some more guidance on what each book is about. You should start to see those changes rolling in shortly.

We also want to continue converting our books to RST. A lot of our books have already been converted, but we still have quite a few to go, and determining which books are to be converted in each release and who is responsible for doing so can take quite a bit of planning. This time around, we’re looking at the Architecture Design Guide, the Operations Guide, and the Configuration Reference Guide.

Finally, a fairly small thing that should have a big influence on our work is tweaking the way the docimpact tool works. At the moment, it creates a lot of noise in our bug queue and makes it harder for us to find the real work that needs to be done. By changing the way this tool operates, we hope it to make it much more responsive and useful both for the docs team, and for the OpenStack developer community.


This release is about having docs work more efficiently and effectively as part of the OpenStack development community. With OpenStack moving to the big tent, we need to reevaluate which projects we document, how we go about communicating with other development teams, and we need to ensure we’re being good community citizens. I also want to ensure we’re working closely with enterprise writing teams, and valuing the input that our corporate contributors provide to the documentation.

Liberty was my first release as Docs PTL, so I’m still learning what makes a good release. It was great to hear feedback from the docs team on what went well and what didn’t go so well, so I can learn from this to improve in Mitaka. I’m very grateful to have a team that has supported me in my new role, and I am honoured to be leading them again into the next release.

Finally, we always need docs contributors. If you are a technical writer, then we have plenty of projects that can use your writing expertise. If you’re a developer, even if you don’t think you’re a good writer, then we could definitely use your technical prowess to test and improve our documentation. Remember, the documentation is developed exactly like code within the OpenStack system, so if you’re an ATC, you already have the skills required to contribute, and to improve the docs for all our users.

Leave a comment

Content as a driver of change – Then & Now

Humans have always written things down.

Those of you reading this post, with your laptops, and mobile phones, and iPads, and vanity email accounts, and your single sourced, content-reuse, DITA-compatible Docbook XML toolchains, with all your fancy Javascript elements and mind-boggling CSS overlays. You are just the latest in a long line of human beings who have been doing the same thing for millennia. Albeit with different tools.


The original owners of the land we are standing on today are the Wurundjeri people. Australian indigenous art is the oldest unbroken tradition of art in the world. These weren’t just the pre-history version of hanging a Monet print on your loungeroom wall. Indigenous art exists on all manner of things: paintings on leaves, wood and rock carvings, sculptures, and of course cave drawings. This art gave early Australians a way to record the things that mattered most to them in their lives: they often involve scenes of hunts or special ceremonies. In the case of Australian art, many include megafauna and other extinct species, and even the arrival of European ships. More than a record of events, though, they were probably also a method of teaching. Each indigenous tribe had its own mythology (collectively known in English as ‘the Dreaming’), which used stories to convey morals or other educational information. Most children who grew up in Australia would be familiar with the Dreamtime story about Tiddilik the Frog, a fable about greed and about finding humour in bad situations. Indigenous art and the stories that lie behind them are really just an early technical manual for life itself, especially in a world where living for any length of time could be quite difficult.


Who here remembers the story of Archimedes and his bath? It’s a demonstration of how Archimedes used water displacement to measure the density of an object (in this case, the king’s crown). Of course, the bit we all remember of the story, though, is that Archimedes, having made his discovery in the bath, went running naked through the streets of Syracuse, crying “Eureka! I have found it!”. This story comes to us from one of the oldest surviving technical manuals in existence, the “De architectura” by Marcus Vitruvius Pollio, which was published in around 15BC. Of course, the Ancient Greeks & Romans were well known for their literature, their scholars, their philosophers, and perhaps above all, their library. The Royal Library of Alexandria in Egypt was the largest repository of knowledge in the world between the 3rd century BC and 30BC. The famous fire that destroyed it was probably set by Julius Caesar himself in 48BC, but the library continued in some capacity until the Roman Emperor Aurelian destroyed what remained in about 270AD. This was of course a massive blow to literature, but it also an incredible loss of technical data as well. Thankfully, the Ancients managed to keep going even after the library was destroyed, and we now have surviving copies of wonderful pieces like Pliny’s Naturalis Historia, which is essentially the world’s very first Natural History encyclopaedia, and which set the stage for many more technical manuals to come.


Jumping over to Europe, Gutenberg did his thing with the printing press in the mid 1400s, but printed books were still a terrifically rare and expensive thing until well into the 15 and 1600s. Up until that period, if you were a fairly ordinary person in a fairly ordinary European town, you were probably aware of the existence of almost exactly one book: the bible that your local clergy had sitting on a plinth in your church. You probably couldn’t read yourself, or if you could probably not well enough to be able to read and understand a book written predominantly in a particularly stuffy version of Latin, and even if you could read that well, you wouldn’t be allowed to touch it. No, the bible was the word of God, and as such could only be read and interpreted by men of the cloth. They didn’t really want people going off and reading the Bible on their own and drawing their own conclusions about things. Of course, this got really interesting once the Reformation really started to get underway in the mid 1500s, and people started to read the Bible for themselves. In fact, for a little while there in England, Henry VIII decided that ordinary folk (and all women) were banned from reading the Bible. All this running around reading things and learning by everyday people was just a little too much for him to bear, especially when they started disagreeing with him.


Still in Europe, with better access to mass printing, publishing written versions of early verbal history became the thing to do. We all know the Brothers Grimm were writing fairy tales in German in the early 1800s, but they certainly weren’t the first to try and document the oral history of early Europeans. Charles Perrault is considered the original author of many of the Disney favourites, including Cinderella, Little Red Riding Hood, and Sleeping Beauty, and he was writing in French over a century before the Grimms, in the late 1600s. But even he was just writing down stories he’d heard from others. My favourite version of Cinderella comes from Giambattista Basile, published in Neapolitan in 1634, some years after he died. These stories, gruesome as they were before Disney got a hold of them, were intended in many cases to be fables for children, with a moral story, but were also used as cautionary tales for adults. In Basile’s version of Cinderella a husband is warned of the horrors of not being too picky about your second or third wife, he gives a general warning to the household about choosing your housekeeping staff carefully, a warning to parents about treating children fairly, and a warning to young women about being proud. And that’s before we get to the bit Disney likes: “if you’re a good person, good things will happen to you”. Some versions of the story also slam home the opposing moral: “if you’re a bad person, bad things will happen to you”, with both the step-sisters either mutilating their own feet to fit the slipper, having their eyes pecked out by birds at Cinderella’s wedding, or some equally terrible combination. As for other horrifying fairy tales, anyone who has read anything by Hans Christian Anderson will know that they often got worse before they got better. There’s a reason Disney never took on “The Little Match Girl”. For a long time, what we now know as fairy tales were the easiest and most entertaining way for a largely illiterate population to record and share moral stories and warnings.


A ribbon that runs through all of these is the idea of the master and apprentice. These types of relationships began in Europe in the 1300s, and were a way for a trade person to get cheap labour, while a young apprentice got a bed to sleep on, food to eat, and the hope of a trade later on. This system was used throughout England and Europe for all skilled trades: from seamstresses and blacksmiths, to Knights with their squires. However, the general principles of apprenticeships exist throughout the world, with one of the earliest examples being the idea of a Maiko, or a trainee Geisha. Geisha have existed in Japan since around 700, and still take in Maiko to this day. While this isn’t written knowledge, it is an important footnote when we’re discussing the history of content, as this was the main way that specialised technical knowledge was handed down.


Of course, a young apprentice, wishing to remember all the things they had learned, might be inclined to write them down. By the time the Industrial Revolution was in full swing, paper and books had become affordable, schooling was more available to children throughout Europe, and literacy was becoming much more widespread, especially to those bright young apprentices who left home to seek their fortunes. And while young people have written home to their families since ancient times, letter writing really hit its stride around the turn of the century when it became not just a way to record their days and connect with their families, but also a way to explore political and religious matters, and explore emotions: poison pens, love letters, and obituaries are all well represented in letters. Another form of writing more like the manuals we know today of course, is the recipe book. Many household cooks would enshrine their recipes in writing, to be handed down to the next generation. I regularly bake a family choc chip biscuit recipe that has been handed down mother to daughter for at least five generations, and possibly quite a few more than that.

But enough history. The older writers in the audience will probably remember most of these more recent forms of technical communication. Some of the more unfortunate among you may still be working with some of them. In that case, I’m sorry.


Printed books are pretty all of our yesterdays. In some ways, it still feels as though you’re not a REAL writer until you’ve got your name on the outside of an actual book, made out of dead tree, and sent from some printer. I chose a picture of O’Reilly books on purpose, as OpenStack released yet another of our manuals as O’Reilly dead tree version last year, although we have no immediate plans to repeat that in a hurry. Personally, I’m part of the problem here. I love having dead tree reference books, especially for things like Style Guides, which are somehow easier to have sitting on my desk as I write, rather than relying on an internet search (which can, for me, at least, be very distracting. Hello, Twitter!). As for writing them, though? No, I love the idea of being able to catch and fix errors even after publication. Nevertheless, printed books, especially technical manuals, are our history, our present and, to some extent at least, probably also our future.



A close cousin of the printed manual, whitepapers are caught somewhere between marketing material and technical documentation. In digital form, they are probably not going to go away any time soon, but the printed whitepaper has almost certainly been confined to the recycling bin these days. My very first piece of technical writing was a white paper. I had a Marketing undergraduate degree and half an MBA, so it was a fairly logical piece of work for me to be doing at the time. I enjoyed it immensely, and immediately set out to become the whitepaper expert, intending to build a career around it. Thank goodness I discovered technical manuals in the meantime, and was saved from a life of writing whitepapers!


And, finally in the ‘recent’ category, I have a screenshot from my very own project. This is, for all intents and purposes, an online version of a printed ‘book’. It has a table of contents down the side, divided into chapters and sections, and it’s designed to be read from beginning to end: simple concepts at the beginning, more complicated procedures as you move through, with reference information (tables of data, contact details, and a glossary) at the end.

These have all been great methods of getting information out there, but they are all destined to become as archaic as the fairy tales and the cave paintings we discussed earlier. Let’s take a look at those things we’re doing a little differently today, that will drive the way we revolutionise and improve content management in the future.


First of all, I want to briefly touch on MOOCs. These are the future of face to face training courses. MOOCs not only allow people all around the world to study when and where they choose, but they also allow institutions to create online tool that mimic real world scenarios, and allow students to learn real skills in a safe environment. This is great especially for the tech industry, where students can work on realistic IT setups that they might not be able to recreate in their own environments, but it also works well for teaching other knowledge work skills such as customer service and financial skills.


The main thing that, I think, changed the way we looked at the information we were creating, was DITA. Of course, DITA isn’t new. It was named in 2001, and formalised in 2005, but varying groups have been working on data mapping and the like since the 60s and 70s, and it became especially popular in the 90s, with the publication of JoAnn Hackos’s book ‘Managing Your Documentation Project’ (and later ‘Information Development’) a book probably most of us have on our shelves, and to which I (at least) still refer to regularly. DITA was really the first formal, open standard that let us consistently and accurately categorise data into formal types. And it was simple enough that we could all use it, remember it, and above all teach it to others easily. Even if you’re not using a specific DITA tool, the general principles of DITA–splitting content into one of only three data types–could be used to underpin any tooling system.

Of course, the main driving principle behind DITA (besides the categorisation) is about content reuse and single sourcing. This is another key component of how we’re changing the way we look at content. It’s not about a beginning and an end any more. With this idea, we walked away from the age old idea of delivering a story, and moved towards this critical period of considering what information is required where, and when. This was important mostly because we were actually starting to consider how people consume information, and learned difficult concepts. We no longer assumed that information we gave to people in the beginning of a book stuck with them as they moved through the rest of the content. Sometimes, learners needed to go over information again and again before they actually learned it and could apply that information to later, more complicated, tasks. And, being the inherently lazy writers that we are, we didn’t want to retype that every time. So single sourcing and content reuse were naturally very easy for us to adopt.

And that leads me to perhaps my favourite topic right now: every page is page one. This is a model designed by Mark Baker, and while his model is certainly not the only one out there, it’s certainly one of the best developed. The general idea behind this is that no piece of content is more or less important than any other. It’s not quite DITA, in that a ‘page’ in EPPO terms is much bigger than a ‘topic’ in DITA terms. The best example comes from Baker himself, where he refers to a recipe. A recipe contains, in DITA terms, a concept (some information about the recipe, that describes what you’re actually creating, and maybe some background, where the recipe has come from, and the types of ingredients that you need), followed by a procedure (the actual steps of the recipe), and finished with reference information (serving suggestions, maybe information on converting measurements, or ingredient substitutions). In EPPO, the entire recipe is the ‘page’: it contains everything you need to be able to perform the task, including all that concept and reference info. One of the best ways to think about EPPO is in terms of a Wikipedia page, there are links to further information if you need it (and I’m sure all of us here have gotten sidetracked by clicking those links in a Wikipedia article!), but that page contains all the specific information about a particular topic. There is no beginning to Wikipedia, and there is most certainly no end.


So this leads me to the big question: what does the future hold for content? I think there are a few main themes we can tease out of our little journey through documentation:
The internet is making things possible that never were before
Control over content is shifting from those producing it, to those consuming it.
Consumers are used to being able to search vast resources for content, and filtering those results themselves. They don’t want us to tell them what they need to know.

Since well before the birth of Christ, in one form or another, we’ve been writing stories. Now the internet allows people to create their own stories, not just have one told to them. In many ways, this shows a maturation in human development: we’re no longer willing to receive whatever is fed to us, we want to create our own realities, and we have the tools to be able to do that.

But that is a massive challenge–and (I would argue) an opportunity–for technical writers. We get to break new ground, and thankfully we’ve been working on the building blocks of this type communication for a few decades now. The challenge now is to start delivering documentation in a completely new way, without leaving our organisations, our management, or our more stubborn clients behind. Nobody said breaking new ground would not require effort, or determination. As we shed old ideas, old processes, old technologies, and old systems, there will be people who decry change, and impede our progress. But even if you only manage to implement a small piece of your grand vision, even if all you ever get to do is plant a seed of an idea in someone’s head that maybe–just maybe–there’s a different way to do things, then you have succeeded. After all, every one of the pieces of content I have mentioned here had its detractors, from every day ‘concerned citizens’, right up to royalty, and the literati.


I mentioned Archimedes earlier, but now I would like to pick a different quote of his: give me a lever and a firm place to stand, and I shall move the world.

Right now it seems to me, that where we could go next is almost infinite. People have always created and consumed content. As long as we continue to put the information out there, and give people the tools to find it, they will continue to do so. We are not at the end of a journey, nor at the beginning of one. We are merely at a step along a very long road. Let’s find out where it leads us.

References: https://docs.google.com/document/d/10meNxWpeiyYprcQjOFIBZJlm3xEiWgarN5GVk1uhJOM/edit?usp=sharing

This was originally presented as a keynote at the Australian Technical Writers’ Association Conference in Melbourne on 23 October, 2015. No video recording exists of this talk.

Leave a comment

linux.conf.au 2015 – Day 3

Started out in Marco Ostini’s security talk, where he scared the pants off us all. Like we weren’t all paranoid enough by default. Then the scaring-the-pants-off-us theme continued with Leslie Hawthorne discussing patent trolls.

After lunch, I headed over to the big lecture hall to hear Brenda Wallace talk about the Christchurch earthquake response, which was incredibly fascinating. I recall when the earthquake hit, and I (sitting in my very safe house, in my very safe street, a very long way away) was glued to Twitter for days watching the crisis response unfold, including the amazing work of the Catalyst team and volunteer army. It was great to get more insight into what was really going on.

Then it was off to hear Leslie Hawthorne’s amazing talk on privilege. There’s a whole heap more blog posts and thoughts in there that I need to unpack a bit more yet, but for the record here are the five experiments Leslie wanted us all to try:

Experiment 1: Change your speech defaults (gay, crazy, lame, guys, like a girl)
Experiment 2: Listen to people who aren’t like you (socmed. #notallmen)
Experiment 3: Change your online persona (woman, PoC, person of size)
Experiment 4: Speak up for others (recenter convos, bring convo back to people ignored or interrupted, use respect)
Experiment 5: Ask for help and accept it humbly (apologise sincerely when you make a mistake)

And the main takeaways for me personally were to

    Ask more questions, make fewer assumptions

, and most of all:

    Stop interrupting

. Feel free to pull me up if you notice me breaking these :)

Tomorrow: my turn!

Leave a comment

linux.conf.au 2015 – Day 2

Eben Moglin kicked off the day with a fabulously inspiring keynote about openness, during which my swag-provided coffee cup decided to demonstrate its grasp of ‘openness’ … all over my laptop. My favourite quote from the talk was his assertion that we need to invoke Asimov’s first law of robotics, and we need to do it NOW. We all carry, essentially, robots in our pockets in the form of smartphones, and they are inherently designed by their creators to harm us. Our technology is working for its creators, not us. This brought back fond memories of Scott Ludlam speaking at the Penguin Dinner at LCA in Ballarat, referring to the fact that we’re all carrying tracking devices around with us. How like LCA to continue to make me paranoid about my devices 😉

Next up was Dr Pauline Harris, who gave a fascinating talk about Maori Astronomy. I knew nothing about Maori history, but had noticed how ingrained Maori culture was in modern New Zealand culture during my last visit over here. Dr Harris gave me some great googling points, and if you’re at all interested in Australian Aboriginal history, then reading about the Tohunga Suppression Act of 1907, the Maori Wars, the Native Schools Act of 1867, and the work that has been done in modern years to reenergise and support the Maori community is absolutely fascinating reading. I always come home from LCA having learned something I never expected to learn. This year, who knew I’d come home with some basic knowledge of the Maori pantheon and how important astronomy was to their culture.

I spent the rest of the morning at the Community Leadership Summit, which I hope to return to later in the day. Fabulously diverse range of topics within this sphere, and I’ve drafted at least three new blog posts as a result of the conversations, so I won’t go into greater detail here. Suffice to say: if you’re in an open source community (in any position, not just leadership), then it’s worthwhile checking out the videos from this miniconf, and I really hope it returns in future years.

The afternoon I spent at the OpenStack miniconf, run by my esteemed colleague Michael Still, shown here opining about Nova. Apparently he’s a big deal in OpenStack networking.


Leave a comment

linux.conf.au 2015 – Documentation Miniconf

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.

2015-01-11 (1)

Leave a comment

Three thoughts on hiring, from my couch

Last Thursday morning I tore my calf muscle at the gym towards the end of a boxing circuit, which put me on crutches for three weeks. Now, at the end of my second weekend on the couch, and eleven days cooped up in my flat, I feel like I’ve got some observations to make. Nothing like an enforced extended period on the couch to turn even a self-confessed hermit into a philosopher, huh? So here I present to you: three thoughts on hiring, from my couch:


Everyone knows the IT industry has a diversity problem. A large reason why we have that problem is also one of the things I love the most about it: we hire through referrals, not job ads. Believe me, this has caused no shortage of anguish in my fevered mind as I’ve lolled around with my leg elevated. I’ve been working on a presentation for linux.conf.au in January and one of the main points I talk about is how we go out and hand-pick great people then work out a role that suits them, rather than creating a job and then going out and finding someone to (more or less accurately) fulfil that role. The great thing about this approach is we don’t have to hire the least mediocre person available, but can wait for a superstar. The problem is who we recognise as superstars, because history and statistics tell us that the people we think are superstars are going to be uncannily like ourselves. Which is how we end up with a whole industry full of white American men aged between 25 and 35 with an unhealthy passion for Mountain Dew.

Let’s imagine for a second that you work in IT, and you would, at some point in the future, like another job in IT. Looking at the ads on seek.com.au isn’t going to get you too far, but there are several things you can be doing now (and should be doing now, even if you’re not planning to change jobs soon) that can help you when you do decide to make that change:

1. If you work for or notice a manager that you really like, then strike up a personal relationship with them immediately, not when you need a job. You know the smelly kid in school who no one liked, until his parents installed a pool in their backyard? Hiring managers hate feeling like the kid who just got a pool for Christmas. People you respect and admire will rarely offer to mentor you, so if you respect them enough to want to be mentored, then go up and ask them. They’ll probably be flattered, and a casual friendly coffee once a month or two is enough to make sure they don’t forget who you are when they have a suitable role come up.

2. Network, network, network! Look, I’m as much of a hermit as the next nerd, and to boot I’m a single parent, so getting out is hard sometimes, I get that. But put some kind of effort in. If you can only make one conference a year, make sure it’s a conference where the people and companies you want to work for are going to be, then dress nicely and go out and talk to people. If you can’t make evening networking events in your city, then take time out of your day to go to lunchtime meetups (assuming it’s within your industry, your boss should be happy to let you go). If meeting face to face is completely out of the question, then be active in online spaces instead: mailing lists, IRC, Google+ and LinkedIn Groups, and relevant Twitter hashtags. Just don’t be an arsehole, because that stuff will come back to haunt you later.

3. Don’t email hiring managers to ask for a job and expect them to fall over themselves to hire you. You’re not that great. Always make a point of asking in person if you can (over a coffee or lunch, or in a private conversation at a conference or other social event). If that isn’t possible, then at least try for a Skype chat or Google Hangout. I love the solitude of working from home fulltime, but I will always appreciate someone going to the effort of seeking me out and talking to me like a human being, rather than just a job-giving robot.

And a bonus especially for hiring managers, just for good luck:

4. Take on mentees, especially if they’ve gone to the effort of asking. And try your very best to take on mentees with skillsets or from backgrounds that are different to yours. It’s easy to mentor someone just like you, but when you get all “oh, I was once young like you” with them, you start to turn into a bit of a dick. Mentor someone who isn’t like you, and you just might learn something new yourself.

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?


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.


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.


Watch the talks mentioned in this blog post: