On Writing, Tech, and Other Loquacities

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


Leave a comment

OMG, my ACL! Second week

I saw my GP again on Tuesday morning (12 days after the injury), and we decided that going to a private surgeon at this point would be a good idea. Waiting times for ACL surgery through the public system can apparently by six months or more, and I was eager to get back on my feet. By this point, I could fully weight bear on my bad leg, and had ditched the crutches for my trusty cane (which I bought years ago when I hurt my calf muscle, and was quite pleased to be able to put back into service). My knee was still swollen, although it was going down ever so slowly, and I still had zero stability in the knee, although that’s not terribly surprising.

I was referred through to QCOS at the Wesley, and I secured an appointment with Dr. Davies on Thursday (14 days after injury). By the time I saw Dr Davies, I was hobbling quite effectively on my peg leg (remember, my brace was still locked straight at this point), and could do a few steps in a straight line without relying on my cane.

The first thing Dr. Davies did was look at my MRI and explain the injury to me. He showed me where the meniscus was torn, and where my ACL wasn’t. For my part, I did my best not to throw up on his desk. He then examined my knee, pushing and poking to work out how much give there was in the joint (spoiler: too much), and asked me to bend my leg as far as possible. At that point, I could get to a very uncomfortable 50° or so. It’s hard to describe the feeling, but it’s almost dry, like there’s no lubrication in my knee, and there’s a lot of pressure on the joint when I bend it.

Dr. Davies then unlocked my brace to 60°, prescribed me to see my physio twice a week, and booked me in for surgery for 19 June. I had four weeks to build my leg muscles back up, and get full range of motion. This, I will note at this point, was in direct contravention of what the physios at the hospital told me. Dr. Davies was polite about them, but I won’t be. They gave me bad advice, and set my recovery back by at least a week by telling me not to move my leg, or to keep working on range of motion. Additionally, locking your knee straight puts pressure on the ligaments that are trying to heal (they are at rest at around 30°), so it’s counter productive. If you get told this, seek an opinion from another physio.

So at this point, two weeks after the injury, I finally had a plan for getting on my feet again! Four weeks until surgery, six weeks rehab afterwards, nine to twelve months before I was fully back to normal. It seemed like forever.

Share


Leave a comment

OMG, my ACL! The first week

I sat around and felt miserable for a couple of days over the weekend, then went to the GP on Monday, and got the MRI done on the Tuesday (four days after the injury). This was my first MRI ever, and I have to admit I was not prepared for the clunking and beeping that machine makes. All the noises sounded, to me anyway, like alarms going off, and I kept on expecting someone to come charging in and pull me out because the machine was malfunctioning. Needless to say, they didn’t, and that’s normal operating procedure. Who knew?

My GP called me with results on Thursday evening. It was not good news: a torn ACL, sprained just about everything else, and a torn meniscus. Surgery was looking to be a distinct possibility. At this point, I could partially weight bear on the bad leg, probably around 50%. I’d been taking Panadol (paracetamol) for a few days, and still was before bed to help me get to sleep, but otherwise wasn’t in much pain at all. My knee was still very swollen, though, and I really needed to wear the splint 24/7, without it my leg felt … well … *floppy*.

Friday was my followup appointment at the hospital (eight days after the injury). Sadly, I didn’t get to see the same physio, instead I saw two others, who surprised me by telling me that I didn’t need to see a physio before the surgery, and sent me down to get a new brace, but that it would be fixed in a straight position until after surgery. This contradicted what I’d read online, but I trusted them, since they were the professionals (and since I have a healthy skepticism of anything I read online). They gave me a referral to a surgeon, and once I had my fancy new exoskeleton brace, I was on my way again.

Read on …

Share


Leave a comment

OMG, my ACL! The day of the injury

So the story begins early on a Thursday morning, at a boxing class run by my trainer, B. I was doing a set of split box jumps on a fitness step with three risers (like these ones). On the seventh rep, my left foot landed on the ground, and presumably twisted, my knee went pop, and I went down with a yell. Interestingly, there was no immediate swelling or bruising, but I was in excruciating pain, so I think from the perspective of everyone else it probably looked like I was complaining about not much. Well, I showed them! They got me lying down with a rolled towel under my bad knee and an ice pack after I started going into shock, while an ambulance was called. When the ambos arrived, they gave me a green whistle (Methoxyflurane. Incidentally, I learned that this is an Australian invention We’re a smart bunch here in Aus, aren’t we?!) which pretty much took care of the pain, and had the upside of making me fairly entertaining on the way to the hospital.

When we got to hospital (RBWH) I was seen pretty quickly by a doctor and a physio, and had an xray to rule out a fracture. The standard way, I’ve learned, to diagnose an ACL tear is to grab the lower leg and push against the knee to see how much sideways movement there is (if this is making you cringe just thinking about it, then you can probably guess how I felt about it at the time). The physio tried this with me but I tensed up so much (“guarding” was the term he used in his report) that he was unable to diagnose me at the time. Eventually, he said he thought I’d probably done my ACL but he couldn’t tell, gave me a knee splint and some crutches, a referral to my GP for an MRI, and a followup appointment for a week’s time.

Read on …

Share


Leave a comment

So that happened …

As many regular readers will know, I’m a bit of a gym junkie. And if you’ve ever tried to book a meeting with me early on a Thursday morning, you’ll know that that is when I do Boxing. Every week, without fail. And so it was a couple of weeks ago. Towards the end of a 45 minute session, I was most of the way through a set of split box jumps, when my knee went pop, and I fell to the ground. To cut a long story short, I ended up with a completely torn ACL, minor sprain of the PCL and ACL, and a meniscus tear. Basically, I did a good job (in blog posts like this, I’ve learned, here is where they often put a gory picture of the inside of a knee, which I’ve taken to quickly scrolling past, so I’ll leave googling for that image as an exercise for the reader).

Normally I don’t write about this kind of thing, but as I’ve been laid up I’ve been doing a bit of googling about knee injuries and the surgery that goes with them. It’s a very common sports/gym injury, and there’s lots of info there, but not a lot from an Australian perspective, so I thought I’d spend some time chronicling my experiences, and hopefully it’ll help someone out.

Day 1
The first week
The second week

Share


Leave a comment

Leadership is not management: Carrots and sticks in an open source community

This article was originally written for http://superuser.openstack.org/articles/leadership-open-source-community/. I will be publishing a more detailed version shortly.

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’.

Share


Leave a comment

What’s the Matter with Meritocracy?

The word meritocracy was formed from the Latin mere (“earn”) and -cracy, from Ancient Greek krátos, “strength, power”. Michael Young is acknowledged as the creator of the term, in his 1958 book “The Rise of the Meritocracy”. In his introduction to the 1994 edition, he implies that he was more concerned about acceptance of this word with both Latin and Greek roots (“I would … be laughed to scorn” he says) than he was about acceptance of the content. However, as history now shows, the word has caught on, and no one seems to care about its mongrel roots too much. The original book was actually a satirical essay, designed in the style of Huxley’s “Brave New World” and he aimed, he says, “to present two sides of the case–the case against as well as the case for a meritocracy. It is not a simple matter and was not intended to be”.

Of course, he’s absolutely correct, meritocracy is not a simple matter. That doesn’t seem to stop people using it as an overwhelmingly positive word, especially in open source communities. I’ve often seen it used in conversation as an argument-stopper, especially when there’s complaints of unfairness or issues with governance. “But we’re a meritocracy!” is enough to shut down any perception of bias, at least for some people.

The interesting thing about meritocracy, especially as it’s practiced in open source communities, is that it puts the blame for not being successful back on the individual. If you haven’t risen to the top of the field in a meritocratic society, then it is simply because you don’t have merit.

Don Watson explored this idea in his recent Quarterly Essay (Issue 63 2016), saying:

Even feudalism spared the poor that insult: their lowly station was an accident of birth. While the underclass in an alleged meritocracy might be reluctant to acknowledge the wound to their dignity, the elites should not be surprised if it adds a savage streak to popular resentment.

Of course, there’s no such thing as a perfect meritocracy, mostly because ‘merit’ is extraordinarily hard to measure (Young’s fictional society relies almost solely on IQ testing), but mostly because human nature means we will always select some people over others merely because of bias. For example, if I’m a person with a decision-making capacity, I’m likely to infer that someone I’ve successfully worked with before has more merit than someone I’ve never met. There’s also a more subtle and sinister bias at work here, though, where older, white, straight men are automatically assumed to have more merit than people that belong to a minority. Interestingly, ‘minority’ in this sense can also mean someone who is not seen to be a developer, so the numbers of designers and, yes, writers in open source communities remain quite low.

What further complicates this issue in open source communities is a general unwillingness to spend time on coaching new contributors, whoever they are. Vitorio Miliano explores this in her blog post Designers and women in open source, saying:

What you see as spoon-feeding is what normal men and women … see as proper, instructive socialization. “Hi, welcome to the community, here’s a housewarming present, here’s how things work, we could really use some help over here …”

So, we have the standard social problem of inherent and largely unconscious bias, combined with a culture of unwillingness to educate new contributors, but we plaster all of that over with a “but, but, meritocracy!” bandaid so that we can tell ourselves it’s alright, the reason some people are at the top of the pile is because MERIT.

And people wonder why I laugh when they use the term.

Share


Leave a comment

SMH scaring elderly Type 2 patients about NDSS changes

I got a letter from the NDSS the other day.

And then yesterday, I saw this article in the SMH.

My first thought on reading the article was “I don’t remember the NDSS letter reading like this”. My second thought was “Hold on, how are they getting test strips for $1.20?!”.

TestStrips

But they had a picture of a lovely older guy looking concerned, so I decided to do some fact checking, which Harriet Alexander clearly was not able to do, in her hurry to write a complete beat up designed to scare elderly Type 2 patients.

So, here’s the facts:
* If you’re on insulin, you will continue to get subsidised strips (regardless of what Type you are)
* If you’re newly diagnosed as Type 2, you will get subsidised strips for your first 6 months’ supply (that’s 900 strips)
* After that, your doctor can write you a letter to continue to get subsidised strips for another six months
* There is no limit to the number of subsidised strips you can get with your doctor’s letter

Speaking as someone who was diagnosed as Type 2 and not on insulin for nearly a decade: if you are unstable enough to need to test regularly, then you are unstable enough to need regular checks with your doctor, at least every six months. Get them to write you a letter already. End of problem.

Haidee-Merritt-Diabetes-FingerPricks-5-400x299

The real news that got buried in this beat up? Insulin pump supplies are now going to be available from NDSS pharmacies, instead of only through DA. And I’m not a pump user, but I think that’s a massive step forward. Well done, NDSS and DA. Thank you for all that you do to support diabetics.

And if anyone works out where to buy 100 strips for $1.20, let me know?

Share


Leave a comment

How Did I Get Here? Good Question!

Fitness First have been displaying a fairly bewildering advertising campaign over the past few months. The first ad in the campaign I saw happened to be this one:

ffbride

I felt compelled to drag a hapless staff member off the reception desk to explain it to me and, to her credit, she tried, but in the end had to admit that it didn’t make much sense to her either. I pointed out that I had found myself in similar situations, but going to the gym had very little to do with it. I had to look further afield. When the campaign launched, the advertising journal Mumbrella got this quote from Sam Bragg, head of marketing at Fitness First Australia:

Yes, fitness is a hard sweat and you’ve got to work at it, but the end result can lead to a range of emotional and physical benefits. That’s why Fitness First exists, to get you to that moment.

Which is all well and good, but if you need it explained to you, then I think the campaign has, to use a technical term, failed miserably.

So I decided to do the only thing a truly sarcastic gym junkie could do: answer the question.

ffbride
Got drunk, went home with a random, grabbed a burger on the way. Turned out the guy fell asleep before there was any action, but on the upside, the burger was tasty. Luckily, she can hold a plank for over two minutes and her extraordinary abs helped her sneak out without waking the neighbours.

ffgrandma
Her grandchildren slipped psychotics into her dementia meds, she went wandering the streets of Sydney, stumbled down Oxford St in a haze, and was crowd surfed into the nearest club. She has no idea what’s going on now, but this guy here has lovely pink suspenders on, that her grandson would probably adore, and can you please tell her where you bought them? I’m assuming she can also bench 80kgs. At least.

ffdrummer

He drove to the venue in a black van with his kit in the back, it’s been a really long set, and if doesn’t get to the bathroom at the end of this song there’s going to be Incident that probably get him kicked out of the band. Again. Thank god he’s been working on his glutes!

ffmumjump

The family has been at this secluded swimming spot for hours, the kids won’t quit complaining about having no wifi, and their father pissed off in the car on some pretext about icecream over an hour ago. If she climbs far enough up the rock face maybe she’ll be out of earshot. Luckily, she has six months of Pump class to thank for her extraordinary upper body strength.

Spotted any other ridiculous “How did I get here” ads? I’d love to caption them for you!

Share


Leave a comment

Lean the hell out of the way

During the Summit in Austin, I had the privilege to attend Upstream University as a mentor for the second time (my first time was in Vancouver in 2015). Between this, and some other stints as a mentor in varying capacities over the past few years, I’ve started to develop some opinions on what makes a good mentor. And the main one that has stuck out for me is probably the opposite to that white women screed of Marissa Mayer’s, Lean In. In the case of mentoring, it’s less about leaning in, and more about leaning the hell out of the way.

It’s important to connect with your mentee, and really understand where they’re at. Not just in terms of their grasp of the technology, but also in their general maturity (many of my mentees recently have been quite young, and not necessarily very worldly wise), understanding of community groups, and ability to ask the right questions. In many cases, the questions your mentees ask are not the ones they require answers to, and so it’s important to be able to dig down to the real problem before you deliver an answer that will just further confuse them.

Once you’ve done all this, you’ve outlined their task, and you’ve given them the tools they need to succeed at that task, it’s time to get out of the way. Go and check your email, do whatever it is you do all day. Feel free to check in if you haven’t heard from them in a while, but don’t be hovering over their shoulder. They will never learn if you’re there, ready to catch them before they fall. Just like with children, once they’ve fallen help them up and put a plaster on their skinned knee, but above all make sure you teach them what it is to fail, and what they need to do to fix the problem. If you’re doing all that work for them, then they’re not learning anything. And incidentally, neither will you.

Share


Leave a comment

OpenStack Newton Summit – Docs Wrapup

Everything is bigger in Texas: including the conferences!

DSC_1078

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:

DSC_1099

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!

DSC_1074

Share