EuroPython 2014 - Geek-power to doc-power

15 Aug 2014

Attending the Django Girls workshop was only the beginning of a week-long adventure at what’s considered to be one of the biggest European Python conferences. Over 1200 attendees stormed the BCC conference center at Alexanderplatz to participate in talks, workshops, hackfests, sprints, and other festivities.

I chose to write a separate post for Django Girls and for EuroPython because I felt that even though the two events were interlinked, each event was so action-packed that trying to contain them in a single post would result in a massive clusterfuck of information (and I’m not exactly known for short posts anyway!).

So let’s see…

Hallway track

After hacking at Django Girls for almost 12 hours on the first day of the conference (not to mention conferencing non-stop at OKFestival and running the Write the Docs unconference), I was absolutely shattered and couldn’t actually make many talks (except for the Nix talk by Domen Kožar, which proved itself to be a wise choice, keep reading…)

Thankfully, I wasn’t exactly expected to talk-hop since most of the talks were for more advanced Pythonistas (although they did have some beginner-friendly talks that a few of the other girls attended). I ended up spending most of the week meeting and talking the other attendees in what is unofficially known as the “hallway track”.

I personally love hallway tracks because, similar to the water cooler meetings at the office, they give you the freedom and flexibility to discuss topics that are close to your heart with people who express similar interests. And unlike formal talks or workshops, you engage the person directly and casually, which makes the discussion a lot more comfortable and fun!

So it would be, that I would grab some coffee or lunch or go out to the courtyard, run into either people I know or just someone who happened to be sitting nearby, and strike up a conversation about . This mostly ended up morphing into some great knowledge-sharing, networking, or intellectual debate about technology, science, community, life, the universe, and everything.

By the end of that week I had a much better understanding about different Python-related projects, about the communities and how they interact and operate, and about the people who are driving this crazy clown car called open-source technology. Look forward to new ideas and budding projects coming your way!

Finding my place in the world

The prospect of attending a developer conferene can be fairly intimidating to newcomers. Any society that revolves around skills and expertise tends to examine newcomers with a critical eye, and proving yourself as a valuable member can feel even more daunting task than interviewing for your dream job.

In this sense, I had two advantages that helped me break the ice in a lot of introductions, and relieved much of the nOOb anxiety that would have accompanied me had I simply turned up to the conference on my own steam.

By wearing my Django pony with pride, the attitude of the veterans seemed to automatically adjust to “nOOb-friendly” mode. I felt comfortable asking all the questions, and nobody raised an eyebrow because hey, they already *know* that I’m new so they expected (and were happy to answer) any and all questions that I had.

And when I wasn’t wearing my Django pony, I wore - you guessed it - my Write the Docs button. Between the EuroPythoners who came to the unconference and the EuroPythoners whom I met for the first time, there seemed to be a general nod of approval at “that docs lady” who floated around the conference expressing interest in the projects and their docs.

Developers write the docs! Wait, what?

One of the big discoveries I made during that week was that there is a new generation of developers who not only accept the importance of documentation, but are actually seeking to improve their writing skills. Developers who *want* to write the docs? Inconceivable! Or is it?

It seems that in most open source projects, developers are left to fend for themselves with their supporting documentation. Many project don’t even have dedicated writers, and distributed or remote contributors often have to rely on written communications to publish and promote their work.

With the rise of online marketing, social media, blogs, and all that Jazz, contributors are starting to understand that if they don’t explain what their awesome new code is capable of, they’re risking having a negative or no reaction on the internets.

Not only that, the FOSS user base is getting bigger and projects are coming to the inevitable conclusion that even their geek-docs should be friendly to newcomers. This is true even if the newcomer is an uber-geek to begin with! Newcomer-friendly can mean many things, and it depends on the project and audience, but it’s still something to keep in mind.

So if you write a piece of code, you need to explain to others how to use it. And they have to do it clearly, concisely, and quickly, because the average user is getting smarter and less patient at roughly the same rate that the technology is becoming more complex and intricate.

The doc(tor) is in

While I was conversing and learning about the state of the docs in different projects, I came across similar responses that expressed the same basic idea, “Hey you’re actually a professional technical writer! Could you show us how to improve our docs?”

After double-taking on this for the first few times, it began to sink in that just like writers are encouraged to learn more about the technology that we’re documenting, there’s nothing stopping us from helping developers and others involved with these projects to learn how to communicate better.

And if the Write the Docs unconference is any indication to the general trends in the communities, we have a great opportunity here to bridge the gap between those who write the code and those who write the docs. We had more developers than writers in attendance that weekend, and they really wanted to learn!

I decided to test this theory right away, and while I was sprinting with the Django girls I announced that I’m also available for short doc reviews or questions for any of the projects that were sprinting that weekend. I figured it’s a great way to see what sort of help the projects need.

Before I knew it, I was hacking with the Plone sprinters on one of their readme files, brainstorming with the Django core developers on the structure of their documentation site, and passing unadulterated judgement on the Nix documentation.

Community outreach, the docs way

Sprinting with the different projects on their docs showed me that much like the Django girls, sometimes even veteran hackers need someone to tell them that they’re available to help if they need it. It doesn’t matter if they never end up asking for your help, just being there and supporting them is enough to drive them forward.

For example, the day after I worked on that Plone readme, one of the hackers came up to me with all the excitement telling me that everyone’s response to the readme was so positive that they’re actually using it as a guideline for other readmes.

And the Nix hackers happily told me that they’re already using some of the tips I gave them when documenting code that they’ve been sprinting on that day. Oh, and they invited me to run a documentation training hackfest at their upcoming NixOS sprint.

Who, me? Wait, why not me?? Even if you don’t feel that you’re *the* expert on a certain subject, if you have some expertise to share and someone invites you to share it, it means that they value whatever expertise you *do* have.

In this case it definitely doesn’t matter that I’m not a Plone, Python, Django, or Nix expert; quality documentation starts from basic communication, and these principles can be applied to any technology. So I agreed!

I’ll be traveling to Ljubljana next weekend to hack and sprint and train the Nix contributors on some tech writing 101, and hopefully this hackfest will not only help their docs, but also help me learn how to help other projects who want to improve their content.

Oh and in case you’re wondering, I fully intend on exploring this type of outreach in Red Hat’s community projects, more details on that in my upcoming FlocktoFedora post…

See you in Ljubljana, internets!

 django  girls,  EuroPython