P is for Python!
Oh, the joy of Python conferences. Between Write the Docs, Django, and Python, I am blessed to be surrounded by communities full of smart, kind, compassionate, friendly and inclusive folks from all over the world.
PyCon UK 2017 was no exception, and in fact raised the bar as far as “most awesome people per general conference population” goes. This was the first time I traveled to the UK for this conference, and although I’ve known a few folks from my extended traveling Python family, I also got to meet folks from all over the UK who don’t have the chance to travel much to the continent.
Talks or it didn’t happen
It’s been a while since I presented my “Docs or it didn’t happen” (formerly known as “FOSS DOCS 101”) talk, so it was a pleasure to update it for this conference. Something of a broad-spectrum talk, it highlights the state of open-source documentation practices in the hopes of inspiring folks to open their minds and incorporate some doc-friendly practices into their projects.
Loosely based on a series of articles I wrote for Opensource.com a couple of years ago (yes, you can find them on my Articles page), and heavily inspired by the amazing things that I learn at Write the Docs and Red Hat, I try to cover some key principles that anyone can adopt in their open-source projects.
Every time I give this talk I update the examples and some of the concepts according to the latest developments and conventions in the documentation world. I was excited to see that I had a lot of shiny new things to share, so I hope that the talk was useful and inspiring, and I’d love to hear how folks implement these in their projects.
You can watch the video of my talk on PyCon UK’s YouTube channel!
If you want to check out the slides, they’re up on SpeakerDeck.
The doc(tor) is in
Giving a talk was only a part of my contribution to the conference. I also invited the attendees to find me during the conference days as well as the sprints and ask me anything doc-related. By now a tradition at any developer conference I go to, I try to make my tech-writer brain available to the developers and non-writers around me who might be struggling with their documentation or want to find out more about my world.
I had a bunch of interesting conversations with community members throughout the event, with a few notables that I’d like to mention here, for posterity and inspiration:
-
My dear friend Harry Percival from PythonAnywhere was inspired by my “who gives a damn about what” message and took his first real look at his doc site’s usage analytics. The results surprised him, not only because some topics turned out to be unexpectedly more popular than others, but he discovered that one of the pages actually made it to the top of Google’s search results. This is a very interesting discovery and one that he can now leverage, since he can tweak the content of that page to be more useful and maybe even figure out where readers would want to go next and direct them accordingly.
-
A university professor who teaches his students to work with open-source libraries asked me for some advice on how to document the public-facing repositories (unfortunately most of the task-oriented content is behind the university’s paywall). We came to the conclusion that since the libraries are meant to be used by students rather than the general populace, a simple README should suffice. This README should introduce the readers to the repository and explain that this open-source code is meant for students, with possible links to more information about the university and the programme.
-
The same professor also asked whether it’s better for each library to have a piece of documentation or to have one over-arching document “to rule them all”. This is a very common question, and from my personal experience I find that if the libraries are supposed to be used separately, then each should have a piece of content. If they’re supposed to be a part of some integrated workflow, you should also have a single-point-of-truth document on how to use them together, but then the individual docs for each library don’t need to be extensive, since they’re more likely to be used as reference docs.
Some hilarity also ensued, with quotables from the developers:
-
“Writing documentation is much like eating your vegetables. You know you should do it, that it’s good for you, that you’ll feel great after doing it, but OMG CHEESEBURGER.”
-
“Self-documented code is like code without bugs. It would have been great if it existed, but people never actually write it like that, so we need testing and documentation.”
PyCon or it didn’t happen
As I said in the beginning, the Python community is my tribe and I always feel at home whenever I reunite with my extended geek family in these events.
I’d like to thank again the hard-working and generous committee for facilitating such a wonderful experience and inviting me to participate; even for a conference brat like myself this was a unique and lovely conference, and I’m honored to be a part of this community.
Put this one on your calendars for next year, folks! As for me, I’ll be preparing my talk proposals for DjangoCon Europe now, and of course gearing up for next year’s Write the Docs events.
Until next time,
-That Docs Lady