[Editor's note: While this talk by Camille Acey is aimed at a very particular audience, it contains much that is relevant to anyone who is helping their co-op, collective, or community make use of software tools and resources. Those who want to see FLOSS (Free, Libre, Open Source) software embraced by their organizations will find important food for thought here, as well.]
Years of being one of the "technical people" in activist circles resulted in my being continually called on to help community groups and fellow organizers understand and more correctly wield technology in service of their mission. Using my blogpost "Three Tips for Providing Tech Help to Non-Profits and Other Such Organizations" as a point of departure, I will share my experience and derived best practices.
From "basics", like how to use documents and spreadsheets, to working with databases and understanding security, I have given assistance to a great many groups and the most important part is always the documentation that I leave behind. I can rarely ever just point people to the official software or open source project documentation, I almost always have to rewrite the docs for them in simple language that references their specific use case.
I wish to help community and activist groups make better technical choices so that they feel more in control of the technologies they use. My hope is that in sharing my experiences, I can engage in a deeper dialogue with the technical documentation community about how we can make technical documentation more accessible, easier to reuse, and empowering.
- Conference: Write the Docs PORTLAND
- Year: 2018
Transcript
Camille Acey: Hello, everyone. I am also a new person here, and I'm really happy to be here.
[clapping]
I'm a tech support professional. And as a tech support professional, I truly believe that tech writers are our comrades in arms in the ongoing struggle to help people harness technology. So it's in the spirit of that camaraderie that I'd like to enlist you in the project of rewriting the docs.
Allow me to explain myself. Growing up, I was always known as the technical one — the one people call to help them install software on their desktop or navigate a website or fix a broken phone. Being the technical one amongst my friends and my family got me into all sorts of situations, both fun and frustrating, but ultimately led to my career in the software industry. However, in addition to my role as head of customer success at Clubhouse Software, I'm also an activist and organizer, primarily in my community in Brooklyn, New York City. And though the groups that I work with are always really fantastic, they rarely tend to be techies. So in those cases, I'm once again called on to be the technical one.
Over time, I met other people who were known as the technical ones in our circles of worker owned cooperatives, and activist groups, and nonprofits. And together, a small group of us came to form a group called the Collective for Liberation, Ecology and Technology. Those three, including me, were the core group that organized our activities. And as part of our work, we advise on technical infrastructure and help with social media, and overall just work with nonprofits and other sort of well-meaning groups to raise the overall digital literacy of the organization. As part of that work, we also end up doing a lot of documentation writing, what I call rewriting the docs.
And by rewriting the docs, I don't mean that we go and write docs longhand, or plagiarize the work — the fine work — that all of you do. What we do is get into the organization's context and understand what they understand, and write out documentation for them that speaks to their use case and their people, and enables them to do the work they need to do, and train their people on the software that they're using. Because unfortunately, in the case of a lot of these organizations we're the only technical assistance they have. Most of the money that they have in their budgets, if they have any, goes to keeping their lights on, paying their staff and providing emotional and financial support to the communities that they serve.
So just looking at the images of the few groups that I've shown you that I've worked with in the past, I think gives you a sense that I work with a wide range of groups, and over that time I was able to identify a few kind of common themes across all of them. So I pulled together sort of a brief guide for best practices for working with groups like this. I call it The Guide to Providing Technical Help to Well-Meaning Groups with Little to No Money, and it's a three step guide.
The first thing that you need to do when you work with groups like this: you might have the best of intentions, and they're really, really great people doing amazing work, so you might end up working with them for decades. But to start, you want to have a very limited scope of work that you're doing with them. You want to understand what they need, what they can do, and sort of say how much time you can devote to it.
You also need to be clear about what you need from them in order to make that work. If you need a password from them or access to any of their people, making it really clear what you can do. In the case of this kind of work, that's a large part emotional labor. A lot of them are working far beyond the scope of what they said they were initially going to do, so it's important to have a scope defined in writing that you can draw upon. So later on, when the scope starts to creep past what you agreed on, you can go back to the original agreement and say, "I said I can only do 2 hours a week, and I'm only going to work on your salesforce instance.".
The other thing is to learn their language. In most cases, these groups have reached out to because they're tech savvy doesn't extend very far past Gmail or an odd Excel spreadsheet. So you want to understand and work with the people who are working with the systems that they've asked you to help with, and make sure that whatever you're doing is within scope for them. As the old saying goes, if you break it, you buy it. And a lot of the times, if you introduce new technology to groups before they can handle it -- and with a very limited scope as we talked about — your scope is going to expand a lot, and that new software, that new stack, that new system is going to be your baby.
At a certain point, let's say if you work with this group for a long period of time, you may need to or want to change out systems, but working with them to optimize the systems they already have will put you in a better position to help them select software that will be most user friendly to them. The world is very full, I think as many of us know, with well-meaning Hack Day projects that developers showed up on site to help nonprofits pull together on GitHub; GitLab is full of repos with these sort of half-finished projects. So whenever possible, just optimize rather than switching systems out.
The third thing you want to do is document, document, document. Document what you touched, document what you tried, and also, most importantly, document how to use the systems that are set up. Now you want to document with great specificity and great granularity, but try and keep the language really simple and user friendly so that they can build on it later on. Or if they find someone else like you who can provide them assistance, that person knows, okay, this is what they already try.
So I don't know how many people grew up, or ended up, reading The For Dummies books. I guess this is sort of my first experience with technology. Growing up, I learned DOS and HTML and lots of other things sitting alongside my father, and I was always so excited when a new book would show up. They had these very funny sort of comics in there and guides about, okay, here's what you can handle, and here's a target sign that means this is the main points. Anyway, I really love these books and they were just always so accessible. These days, if you say "for Dummies" it's sort of a slur, or kind of means "dumbed down." But at that time I felt like "For Dummies" kind of meant like "for the people." This is our technology, and this is our field guide to hurtling into our new fantastic techno future.
I had very high hopes at that time. It didn't feel like there was a stratification or a digital divide. However, over time, some 20, 30 years later, I think we can find that though all of us have these devices in our pockets, the digital divide is in many ways wider than ever. And as a worker in the traditional software industry, I accept part of my responsibility for this.
At Clubhouse, we are a company producing project management tools for software teams. We expect our user persona to be anything from a tech savvy product manager who can sort of Google what they can't figure out, to sort of a mad genius hacker kind of builder of all things, who's usually writing and to tell us what features we're missing, or how to refactor the entire system to make it work better for their use case. However, when I'm working with the nonprofits and the other sort of social justice groups, I can't assume this level of savviness, they're just not capable.
And this is not to say that they're uneducated or uncurious. A lot of these people are accomplished lawyers, educators, community-based activists. These are the kind of people that will face down police, and opposition groups, and shout down politicians. However, at the same time, they also will positively melt into a puddle if you ask them about what phone they're using, or the impact social media is having on the oftentimes vulnerable populations that they serve. So when working with these groups, I find that there's few other areas in our daily lives that so many people, at least in my world, routinely excuse themselves from discussing in any depth. So the work that I do and the documentation that I pull together is really focused on not just telling them how to use the software that they've got installed, but also how to overcome that feeling of frustration and that imposter syndrome that they bring to technology overall.
This is all the more important when you're working with people who are really focused on changing the world in positive ways. Silicon Valley and the overall software industry is too economically, ecologically, politically and socially significant to be left out of the equation when devising an analysis of the world. So using understanding and re-envisioning technology is integral to a transformative vision for our planet.
So getting into more specifics, I'm going to share a doc that I rewrote with you. This is it. And if you can't see it, don't worry you don't have to squint, I'll just talk it through. This is a doc that I pull together for a food cooperative. I'm a co-founder of a food cooperative in my neighborhood, and I was the head of the tech committee responsible for setting up the basic systems we needed just to get the thing off the ground. I pulled together this doc after different committee heads kept reaching out to me to ask how they could use the co-op domain email address. Google actually has documentation like this, of course, obviously, but the people that I was working with did not know what an email client was, so they wouldn't have known even what to Google to find what they needed. So I pulled this doc together and it walked through pretty much every step that I think they would need to get into this email.
And of course the docs are in Google Docs because again, that was what people were comfortable with. When we first had the inception of the food co-op, I really was like, "okay, this is going be my dream project and we can use all open source." But as we got in a little bit deeper, I realized this was more than I could handle, and I have a day job and a family. So I just kept it in the systems that they were familiar with.
So onto how I actually rewrite the docs or how we rewrite the docs. And this pretty much maps onto that three step guide to helping groups with little to no money. The first thing is to meet the groups where they are. Again, as I mentioned, the tech savvy is usually not there. So understanding kind of what they need, defining a scope for that work is pretty crucial at the beginning. Working with the software that they have and trying to optimize flows and pull together documentation that they can use to train their people. The second thing is to get into the context. In the example that I showed you about the food cooperative, I knew that the first people that needed it were committee heads. So I mentioned it. It's like, "Okay, you're a committee head, what will you need to make this work for you?"
In this case — this is a Hopewell Care Cooperative, they're a worker owned, cooperative of child and elder care workers — and we knew that the systems that we set up were going to be used by the care workers in some cases, and other systems we're going to be used by the administrators that are also part of that group. So when we put together a training for them and also documentation, we made it clear: "this is the part the care workers do, this is the part the admins do." Whenever possible, it's very important to get into the context and name people by names even, if it helps.
And the third part, after you do the work for them, is to really just document everything that you did and hand the documents over to them so they can test it out. Go away. I think somebody mentioned this: don't talk a lot when you're doing user research. I think you can apply some of those skills here. Go away, let them try it, and get back to you about what was confusing.
And I had a bonus sort of 3a, which is share the official documentation. As I mentioned, for a lot of the groups that I work with there, the "Google hands" are not super strong, so the more you can point them to where they need to go, the better; so that they can try and do a little troubleshooting themselves before they reach out to you for more free technical help.
In the beginning I said I'd like to enlist tech writers help in the work of rewriting the docs, so I'm going to go over a few ways that you can enlist. Again, it's three steps.
So, the first step is to get into the product. A lot of the folks that I work with are not going to find documentation really easily. They're used to paper manuals, so whenever possible, if you can have the link to the documentation in the UI of the product, that's very helpful for these groups in terms of searchability, and trying to solve some of their own problems.
The second thing to do is try and keep your docs up to date and image rich. I oversee the documentation function at my day job. I know how documentation backlogs can pile up, especially in a continuous deployment environment. But as much as possible, try and power through those backlogs, especially when something significant in the UI changes. For the groups that I work with. If a UI changes completely, that might be their whole day gone. So as much as possible, try and be mindful of that.
The third thing is to accept feedback whenever you can. If the groups that I work with do get into that official documentation and there's anything confusing, I'd like to be able to empower them to reach out to you directly, as technical writers, and say, "this doesn't make sense," or "this looks kind of wrong to me.".
I recently came across this page on the CiviCRM docs — and this is not a knock to CiviCRM, we use this quite a lot, we like Civi. But I saw this green pencil up here in the corner and I thought it was pretty cool. I was like, "Oh, I'm going to click this and it's going to be some kind of WYSIWYG set-up where I can change the documentation on the fly." Unfortunately, when I clicked it led me to a page that is just sort of a showstopper for the people that I work with. Nobody's forking anything.
So whenever possible, if you can add an email or some sort of inbox that people can connect to you about the documentation, that's really helpful. And more than just sending you feedback. Please try and make sure there's someone if you can someone actually on the other end of that that will write back and say, "thanks for this feedback," or "these are the things we can do and maybe funnel you along to some sort of support."
So in closing, to rewrite the docs you want to learn their language, learn where they are, get into their contacts, know which kind of people are going to be using it, and make sure you mention them in the documentation so they know this is documentation for me — here's where I come in. And finally, document and test. Make sure your documentation makes sense for them.
And to enlist and be good comrades to us in the radical IT department, get the documentation into the product, whenever you can link to the documentation. Keep your documentation up to date and image rich, and accept feedback in a way that people who aren't super tech savvy can supply it to you. In the work that I do, both in my day job at Clubhouse as head of support — overseeing documentation support, customer success — and also in my community, my highest goal is to let people come to technology, help people come to technology empowered. When I rewrite the docs, I do so to write-in that this doesn't have to be difficult, that this technology can be fun, and most importantly, that the technology is ours. So that's in solidarity with everyone here. That's my email. That's my social. If you're on Mastodon, you can toot at me, and I have links to the organizations that I mentioned on my website, and I'll be adding my slide deck and more information about what I wrote there. Solidarity.
This transcript has been lightly edited for readability.
Add new comment