Last week I spoke at devrelcon London 2019, which was an interesting and fun experience. Firstly, I’d never heard of “devrel” until a few months ago, and secondly, it’s been a while since I’ve spoken or even attended a conference outside of the cosy little Open Source GIS community. For those short of time, my talk was on “Inspiring and empowering users and techies to become great writers- and why that’s important” and you can find it on GitHub for the live version, and the pdf with speaker notes.

Given my complete lack of knowledge about “devrel”, what on earth was I doing at one of their conferences? It comes from the work I’ve been doing administering and mentoring a technical writer as part of OSGeo’s participation in Google Season of Docs (GSoD). The Good Docs Project was spun out of this, like a “meta-project”, abstracting the fabulous work our paid writers were doing for GSod to work with any open source project. As the main UK-based person involved in these projects, I was best placed to speak at devrelcon in London, so there I was.

What follows are my thoughts about the event, take-aways from my talk, and some general musings about “devrel” as it applies, or could apply to open source GIS…

So what’s devrel?

Firstly, I’ve since done my homework and learnt that “devrel”, or Developer Relations, is a relatively new umbrella term, broadly meaning community management for a technical audience. The purpose of it is to build relationships and enable developer communities, be that as liasing between companies and communities, or advocating for community needs. Another side of it is PR or marketing for developers- ensuring that products such as APIs or SDKs reach their target audience. Communities such as devrelnet (the organisers of devrelcon) have sprung up to provide a space where the devrel community can come together and share ideas.

My talk

Clearly areas such as documentation mesh quite well within this fairly nebulous overall idea, and in fact there was an entire documentation track at the event, of which my talk was part. Coming to this event as a complete outsider, or n00b, I thought long and hard about what I wanted to say. Initially I’d wanted to focus on the types of things you should or shouldn’t say in documentation; the types of terms that alienate users and make for a poor reading experience. However, there are so many articles about this, and for all I knew I could be preaching to the converted, or teaching Grandmothers to suck eggs. Let’s face it, no one likes an outsider coming to their event, pretending to be an expert, and telling you about something you already know as if it’s a cool new discovery!

Serendipitously, at about this time I also read some fabulous articles in Increment Magazine’s issue on open source, which gave me a different way in. Along with the GitHub open source software survey (of which 2017 is the most recent published version), I started looking at some of the problems open source projects face, around developer burn-out, coupled with a lack of new developers coming on board, and a lack of diversity. When you also see surveys that show documentation as a “way in” to a project for under-represented groups (be that by gender, language etc) then you start to see a story developing:

Better documentation -> Bigger and more diverse communities -> New developers -> Less burn-out at the top -> Win for everyone

So that’s the angle that I took, then I looked at ways in which users could be enticed to help with documentation, and how in many cases they are the best people to write the docs, particularly when it comes to installation and quick-start guides. I looked at ways in which barriers to entry could be reduced, having seen for myself how easy it is to be put off by a massively difficult documentation work-flow, or missing steps, and how nice it is when as a new contributor you see your first spelling mistake fix reflected in the live documentation.

Finally, I rounded the talk off with a call to arms to get people to join The Good Docs Project, and we also handed out some of the super cute Doctopus stickers!

Questions after my talk suggested I’d made some people think, which is always good. To paraphrase, a couple of interactions went along the line of “I am responsible for the documentation for a large open source project, and it’s a mess, and I don’t know how to even start”. The idea of approaching users to help with this seemed new, as if documentation needs to be the domain of the software project itself, and not the people using it.

Take-aways

Take-aways from other talks in my stream:

  • Build better GitHub experiences as that’s often where developers will randomly land when googling your code (Lorna Mitchell). Think about your readmes and the GitHub tags for a project, which are structured data and will appear in search results.
  • Step up from Docs as Code to Docs as Engineering by treating the documentation deployment process as you would a software deployment (Cristiano Betta). Make it very easy to link between (for example) APIs and their documentation- including adding working API examples within the docs.

Since I could only be there for one day, my experience outside of that track was a little limited- but the devrel crowd were friendly, diverse and all seemed to know each other. I guess (or hope) that’s what people think when they visit one of our OSGeo events too.

Devrel in open source GIS

So devrel in Open Source GIS- do we do it? I think yes, a bit, but without giving it a name. More engagement with other communities, like devrel, would be helpful to remind us that we are part of a bigger “thing” and not just stuck in our own niche. To highlight that- when I talked about what I do, in terms of “open source mapping”, people immediately assumed I meant OpenStreetMap.

Certainly we could learn from the practices being discussed at the event, such as building diverse communities. We could definitely learn better ways of doing documentation (which is where The Good Docs project comes in, of course).

Any more than that, I can’t say for now as it was a bit of a whirlwind (I could only attend one day and then went straight to the Astun Christmas Company meeting) and I feel I need to inwardly digest my thoughts from the event, and learn more about it all. I’ll be looking out for opportunities to apply things I learned though, in both Astun and OSGeo.