How to succeed as a remote documentation contributor in OpenStack

A preview of Alexandra Settle's upcoming talk at OpenStack Summit Barcelona
4 readers like this.
Sky with clouds and grass

Flickr user: theaucitron (CC BY-SA 2.0)

Alexandra Settle, an information developer at Rackspace, will be speaking at OpenStack Summit in Barcelona. Alexandra is a core reviewer for OpenStack manuals, also working on the OpenStack Ansible and Swift project documentation, and serves as a mentor in documentation for the Outreachy project. She's been interested in information technology since high school and is a fan of Fedora Linux. She began her career as an intern at Red Hat and after spending years using Windows machines, and love the ease of use and functionality that came with using Linux.

In this interview, Alexandra shares a preview of her talk on best practices for working from home and being a strong communicator while working on an open source project.

What's the secret to producing good documentation?

I would not say there is a ‘secret' to good documentation. Good documentation is very rarely delivered from one person—it is always a team effort. If you write the first draft, or perhaps an update to a doc, collaboration is key to your success. There should always be several eyes on your original document, an editor (if your team has one) and for technical documentation, there should always be an SME (subject matter expert) available to provide guidance. You cannot be sensitive about your writing. Nobody is perfect, and your writing isn't going to be either. Plus, you learn more when you work with other people.

How do you keep your reader's interest in highly technical documentation?

Highly technical documentation is not something people tend to read before bed. Fortunately, I write for a community of developers and operators. Installation guides, networking guides, and upgrade guides are all pivotal to their functioning work day. However, feedback I have received from support staff, operators, and developers throughout the last few years has been fairly consistent—keep it simple (but never use the word simple: it never is simple and it insults people who do not find it simple). Technical documentation should tell you what to do, how to do it, and if necessary, some contextual information. If you keep it within those boundaries, your audience will appreciate your output.

What are the top three reasons I/we should work from home? How is it both awesome and horrible at the same time?

Three reasons why you SHOULD work from home:

  1. Work/life balance. Provided you have a good understanding with your employer or manager, you can normally function on a different schedule to your 9-5pm colleagues. It allows you to be able to do simple things that, when working 9-5, can be the cause some of life's great pains (for example, going to the post office. How annoying is it when it's always shut after work!).

  1. Your own space. I can't even stress how wonderful it is to have your own office, your own comforts, food, and the choice of not having to dress up for the office. It can make for a very productive environment when you are mentally content.

  1. Joining co-working spaces. This is an awesome idea for anyone who is willing to go into an office a few days a week, but is not ‘the office'. I joined a space called The Swarm in West End in Brisbane. They are no longer in operation, but this beautiful space was renovated and designed by architects—they actually worked in the space upstairs. I was able to meet a variety of creatives and techs who were all working on an assortment of projects. This was a fantastic networking opportunity, that you wouldn't get if you worked from an office, and I would seriously recommend it to anyone.

Work from home is awesome for all the reasons I listed above, the sense of freedom cannot be compared to the 9-5pm life. However, it can be horrible when you do not manage your own time. One of the biggest struggles I encountered was the lack of socializing. I am quite the social person, but I realized within the first year of my work from home employment that I was seeing my friends less, spending more time on the computer outside of my ‘work hours' (checking emails incessantly, checking my changes to a doc patch had merged, trolling through Buzzfeed, and becoming increasingly insular. This was an incredibly hard cycle to break. My work was affected by my lack of enthusiasm for life and after facing my problems, I was able to renew my view on working from home and work/life management.

This is a fairly accurate explanation of all these things, which I used in my Linux Conf talk.

How do you maintain the culture of the organization you work for when working from home?

This was quite difficult, but fortunately, I worked with a team of people that worked from home. At the very least, culture is maintained through communication platforms such as Slack or IRC (my personal preferences). Getting to know each other, even if it was via a textual medium, allowed for the team to cultivate in-jokes, references, talk about emails, work, and perhaps even personal items. As far as maintaining the culture of the organization goes—that is definitely a harder task. From experience, I would say the best way to maintain the culture of your organization is to be involved. Whether this is by reaching out to the closest office nearby and organizing a visit, attending their local meetings on company issues (dial or video in), or joining social committees and reporting on you and your team's external activities. For example, our work from home team found out one month that the Sydney office was having a pizza lunch. Myself and another colleague formed a fake ‘coup' on IRC, and after negotiations with our bosses, we had The Great Pizza Order of 2014. Which, to be fair, did not eventuate into pizza. But, we did look into our team budget and we were able to city-specific team outings and lunch and movies were organized for everyone.

How has Outreachy helped you to grow? What are the advantages of working with interns at Outreachy?

Outreachy gave me a platform to help others. Although I genuinely enjoy teaching people and watching people grow and learn—I am terrible at it. I, self-confessed, am very impatient—which is a terrible quality for a teacher. Tech is not always something people feel immediately comfortable with, and that's quite understandable. Through the mentor/mentee program, I was taught (most definitely by the mentees) to be patient—which is really important when you are remotely trying to teach someone via IRC (sometimes through language barriers too) how to troubleshoot their issues. Sending someone a link to "Let me Google that for you" does not win you any friends.

Diversity was the major advantage of working with the interns Outreachy. The Outreachy program focused the latest round on women (cis and trans), trans men, and genderqueer people internationally. I had the opportunity to meet many different people from very different backgrounds to myself—which was wonderfully eye-opening.

User profile image.
Educator, entrepreneur, open source advocate, life long learner, Python teacher. M.A. in Educational Psychology, M.S. Ed. in Educational Leadership, Linux system administrator.


Great article, Alexandra and Don! While I enjoy being physically proximate to my colleagues for meetings, definitely some of my most productive days are those that I work from home. I'm glad to have some flexibility to do both.

Thanks Jason! I too enjoy working from home. However, it's always nice to see colleagues in person. Skype, FaceTime and other virtual meetings have revolutionized discourse for sure though.

In reply to by Jason B

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.