Jimee, Jackie, Tom & Asha, CC BY-SA 2.0 https://creativecommons.org/licenses/by-sa/2.0, via Wikimedia Commons
A focus of mine over the last few years has been how new users for software are enabled by good documentation, or conversely how easy it is to inadvertently put people off with the language you use. There are countless articles on this, around the use of terms such as “just”, or “simply”, and I’ve made observations myself on other examples over the last couple of years. However, I recently read a series of articles (kicked off by this one from Julia Evans) that made me realise that the debate is actually more nuanced than I had considered, and that there are downsides to using language that’s too simple.
You don’t want to put off complete beginners by overwhelming them with unfamiliar jargon, but avoiding necessary technical terms will be counter-productive in the long-term, as it will be a barrier to further searching and learning. A good balance would be to avoid unnecessary jargon, but introduce vital technical terms with a friendly explanation.
For example, here are three ways of introducing the same concept, namely making a change to some documentation for a project that is hosted on GitHub. Note I have omitted some elements of the process in step three, for brevity. Don’t @ me.
All jargon: Submit changes to our documentation by forking the repository and submitting a pull-request.
No jargon: Submit changes to our documentation by copying the code and sending us a version with your changes in it.
Friendly explanation: To submit changes to our documentation, firstly you’ll need a user account on GitHub. Then make a copy (or fork) our repository under your own account, make the changes there using the in-built text editor, and then submit a request back to us (a pull request). We will review your suggestions and hopefully approve them. If you are unclear about any of these steps, see the documentation at https://docs.github.com/en/free-pro-team@latest/github.
From the perspective of a beginner, the first approach would probably be off-putting as it assumes you already know what the terms ‘forking’ and ‘pull request’ means, so our beginner starts their journey by feeling stupid.
Approach two is an attempt to simplify the language by using roughly equivalent non-technical terms but it doesn’t explain how to copy the code and send the changes, and our plucky beginner will be no better off when they do eventually meet the terms ‘forking’ and ‘pull request’.
Approach three is more verbose, I admit, but it introduces all the terms, explains the process, and provides guidance if needed.
This is where it gets tricky. Plain language is more accessible (for example to people with disabilities), but at the same time if you use language that’s too plain for your intended audience, then you risk appearing condescending. The key element is the for your intended audience part. One definition of plain language states that it is “Language that allows readers to make an informed decision about the content because it considers their literacy levels, cognitive abilities, contexts, wants, needs, attitudes and challenges” (Candice Burt, via https://en.wikipedia.org/wiki/Plain_language). In what seems to have been a well-received experiment, the journalism website ProPublica published some articles and editors notes on disability rights alongside their standard text (https://www.niemanlab.org/2020/11/propublica-experiments-with-ultra-accessible-plain-language-in-stories-about-disabilities/). Your reaction may vary when reading the plain language translation. Personally I wince at using “caring” or a derivative of it, 4 times in a 3-sentence paragraph, but I like the general sentiment.
However, the level of plain language used does need to take into account the expected audience. Sumana Harihareswara writes of mixed reactions to a FAQ on sunsetting Python 2 that was written in a plain language style. When I read that, elements of it do make me cringe, though partly that’s to do with the same issue of repeating words, but also starting sentences with “And”. I think it ought to be possible to write in plain language without doing either of those things.
Finally, I was recently introduced to Hemingwayapp, which does a good job of assessing the readability grade of your writing, and suggests appropriate changes. Not everyone uses a full-blown word-processing package so this is a useful service (and free). Writing for your audience, but also ensuring you don’t alienate or condescend, is a really fine balance to hit- and thinking about these two issues in depth has given me even more respect than I previously had for technical writers!
]]>I was recently awarded a Google Open Source Peer Bonus, which was all kinds of awesome, but also proof that you can contribute things of value to open source projects, and indeed build a career in it, without being a hard-core coder. I can github, it’s true, but my actual coding skills are definitely limited to the occasional python or shell script! So how, as a non-coder can I, and others like me, contribute to open source in a meaningful way?
This is incredibly valuable, particularly if you are new to a project! Firstly, developers and maintainers of projects are often focused, for good reason, on fixing bugs and improving the software. Documentation is harder for them to prioritise, and sometimes gets neglected. If you can help with this, then your contributions will be greatly appreciated. Secondly, if you’re very familiar with how to install and run a particular package, or even if you already have all the dependencies installed, then it’s very easy to miss a step, or for your instructions to be ambiguous. However, if you’re a beginner, you are best placed to ensure that instructions and step-by-step guides are easy to follow, don’t skip vital steps, and don’t use off-putting language.
Also, if you have the opportunity to get involved in projects like Google Season of Docs as a mentor or a participant, as I did in 2019, go for it because it’s hugely rewarding!
Can you help on mailing lists, or by organising events? One of the best things I have done was to get involved in the nascent Open Source Geospatial Foundation (OSGeo) back in 2006. I was persuaded to set up a local chapter in the United Kingdom, which is still going strong 14 years later at https://uk.ogseo.org. We’ve hosted a global conference (FOSS4G) and several UK events; and an online-only event this year. We’ve also managed to financially support a number of open source projects by providing an annual sponsorship, or by contributing to the funding of a specific improvement. I’ve met so many great people because of my involvement in OSGeo, some of which have become colleagues and good friends.
The view from the stage at FOSS4G 2013, photo by me, CC BY-NC-2.0
Can you talk at a conference about your experiences with a project, or perhaps write a case study? Evidence that particular packages can be used successfully in real-world situations are incredibly valuable, and can help others put together business cases for considering an open source solution.
When I first started using open source software, the packages I needed were often hard to install and configure on windows, and had to be started using the command prompt, which is intimidating for beginners. To scratch a problem-solving itch, I packaged them up onto a USB stick, added some batch files to make them load properly from an external drive, added a little menu for starting them, and Portable GIS was born. 12 years, a few iterations, a website and a GitLab repository later, it has been downloaded thousands of times, and is used in situations such as disaster relief, where installing lots of software rapidly on often old pcs is not really an option. I didn’t need any coding skills for this, beyond knowing how to refer to relative drive paths in windows.
Once you get proficient in something, use your new knowledge to help others. Some areas of “modern” software use and development, such as online repositories like GitHub or GitLab are extremely intimidating to new users, and create a huge barrier to participation. If you can help people get over the fear-inducing first pull request, you will empower them to keep on contributing. I confess, my first pull request was a slightly puerile contribution to the Vaguely Rude Place-names map back in 2013! Since then, however, taking a leaf from the Python “Don’t be afraid to commit” workshop, I have run a few training events along a similar line at conferences and hopefully helped a few people take that first step.
In summary, 16 years after I first found out about it, open source is now fundamental to my career, as well as being something that I am truly passionate about. It has shaped my life in many ways. I hope that my experiences might help some people who also consider themselves to be non-coders to get involved, and to realise that their contributions are equally as valuable as bug fixes and patches.
]]>I hadn’t heard of the program until I was awarded it, but it allows Google employees to recognise external (eg non-Google) contributors to open source. The really great thing is that it recgonises all types of contributors, including (copied straight from their blurb):
It’s wonderful to see the full plethora of contributors recognised- and it certainly gave me a bit of a boost and the momentum to carry on doing “stuff” in these *ahem* challenging times. There is a small monetary contribution- which in my case will pay for a couple of days away in the UK Lake District (COVID restrictions notwithstanding).
Through this award, I also discovered the Google Open Source blog, and through that, their Open Source Live event series. The first of these was in early September, and covered “The New Open Source: Leadership, contributions and sustainability”. I found the talks in the main very informative- I’ve been thinking a lot about sustainability in open source since I was researching a talk for DevRelCon last year and reading the statistics about developer and project burn-out. The statistics are unlikely to get any better this year, since there’s such a huge burden of additional stress in everyone’s lives. One particular talk about “Being the leader you want in OSS” was also thought-provoking, as it told the story of a new contributor becoming involved in a project, driving change by virtue of getting involved and asking the right questions, and eventually becoming a core part of the project team.
Note: I’m not meaning to come across as a completely un-critical google fan-girl here. Certain elements of the “empire” are problematic indeed, but this is one area that I think they’ve done well with. There’s a cycle here. Initiatives like the OSPB Program help to keep people going, and to stay enthusiastic, at a very difficult time. People are what make open source projects work, keep them sustainable, and drive positive change. Goodness me, we need as much of that as we can get right now!
]]>It’s weird posting to a mostly tech blog at the moment. The world is on fire, but life goes on, yet I’ve felt utterly paralysed and unable to write anything here. It feels strange and somehow wrong to write about tech stuff, which lets face it, is not that important in the grand scheme of things, when so much other stuff is going on. Yet here we are, blogging.
So what did I want to blog about? Something that I read recently that I have taken to heart, and that has proved strangely apposite during #lockdown. I’m interested in hacking myself so that good/productive behaviour becomes easier and requires less “processing power” to achieve. Things like “Getting Things Done” by David Allen, and the Bullet Journal Technique are important parts of my life, though before you ask my “Bullet Journal” technique is a bit stripped down and doesn’t require the purchase of expensive custom journals…
Consequently I love finding out new ways of fooling my brain into good behavioural patterns, but I have struggled to find the key that works for both “work stuff” and my other great love, climbing. However I recently read “Atomic Habits” by James Clear, and he set out an idea that has stuck with me, and shown benefits in both work and climbing throughout the last few months. It’s really very obvious, but the idea is that training or hard work should be viewed as deposits into a long-term savings account that you’ve set up to save for something really important. Every bit of hardf work or physical training that you undertake will probably not show any benefits in the short-term, but it all adds up. Every time you (or really I) slack off, it’s the equivalent of making a withdrawal. You lose more than just the cash-value, you lose the long-term interest too.
I’ve applied this mainly to climbing training during #lockdown, following a rather gruelling program from lattice training, which involves a minimum of an hour’s training for five out of seven days a week (after work). For two weeks in every four, this goes up to 1.5 hours a day. Whenever I’m bored or tired, which happens a lot, I remember the idea of the savings account, and manage to keep going. So what is the savings account for in this case? Mainly just being the best climber I can be (given the limitations of being a mid-40s female with a full-time job and a bad back). And yes, now #lockdown has eased somewhat, and climbing locally is OK, I can see obvious improvements in my performance, which make it all worthwhile.
How does this relate to open source gis though, I possibly hear you ask? Well, it’s more a work ethos than anything specific, particularly when I’m wading through stuff that’s new to me, or difficult. Cutting corners, or doing a half-arsed job, are all withdrawals from the savings account. Taking the time to really understand something? That’s a deposit.
The flipside of this is that sometimes you just can’t make that deposit. Maybe you’re literally too tired to train, or to think straight. Maybe you’ve over-committed by agreeing to give five different presentations over three conferences, one of which you’re also helping to organise, in the space of two weeks (ahem). It’s not the end of the world though. Missing one deposit is not going to stop you from meeting your target. The key thing is to give yourself the space you need, and then pick it right back up again. Remember also that it’s counter-productive to save for too many things at once- it’s better to limit yourself!
I won’t labour the point any longer, suffice to say that “this one simple hack” has helped me have a surprisingly productive #lockdown, and that having these “long-term savings goals” has kept me focused and sane. I am well aware though, that I’ve been in a position of immense privilege, being able to continue life relatively normally over this period. Not everyone has been as lucky.
]]>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…
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.
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 from other talks in my stream:
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.
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.
]]>