If you follow our blog, you might have seen our definition of digital resilience floating around. To sum all this up: we see digital resilience as a set of practices that support the ability of an organisation to:
- protect itself from, and respond to, digital security threats,
- adopt infrastructures that respond to the ever-changing needs and contexts of the organisation and its members,
- ensure their wellbeing.
Back in July we hosted an “Ask Me Anything” session about digital resilience in social justice organisations and one of the questions we received got us thinking more about point 2 in the list above:
Once an organisation has decided to shift to tech that is more aligned with their values, what are some good practices for creating easy to read/accessible documentation that helps the process of introducing free/safer/privacy respecting tools to their team, especially for people who might not have a tech background and aren’t familiar with these kinds of tools?
Below we’re sharing some of the tips we shared during the AMA, along with some additional ideas for how you can approach the process of creating documentation that supports your team as you adopt tech tools.
Before rolling out a tool…
At The Engine Room, before rolling out a tool we try to have lots of conversations with the team and get on the same page in terms of why we’re adopting a new tool. If it’s a tool that we’re adopting as a more secure alternative to another popular tool (for example, adopting a self-hosted Big blue Button instance to use instead of Zoom),we discuss how these tools won’t necessarily make our lives easier, but they will make ourselves and our partners safer. We test and pilot tools together, weighing the pros and cons of our experiences.
In that process, there are a few things we try to hold on to:
- Not using fear to pressure the use of a tool. Using fear to persuade is not ethical and only leads to stress and panic! We tend to raise awareness by fostering a sense of collective responsibility as opposed to individual fear.
- Remembering that it is normal to feel a bit uncomfortable in a new environment, encouraging the team to take it easy and making sure everyone has access to tech support when needed.
- Remembering that tech tools that are not self-explanatory: some may come with a learning curve, and might require training and support.
- One tool won’t always fit all our needs and desires, so being flexible and balancing out our “must haves” vs “nice to haves” is super important.
On a more practical level, before rolling out a tool, we host introductory or welcome sessions to get everyone familiar with the new environment. In the first few weeks or months of piloting a new tool, we also encourage our team to exercise tech intuition, letting people explore the tool by themselves and making sure our Tech Team is around to offer support if needed.
Be clear on the “why” behind a new tool
One practice that has helped our team in adopting new tools is making sure our tech documentation includes a brief, direct overview of why we have chosen the tool. Our internal “guides” for the various tools we use include a short review of the context of adoption, including why and when the tool was adopted, what we use it for and how we use it. We find that this can be a simple, but effective way of reminding ourselves of our values and how they’re tied to our tech choices.
Create documentation specifically for you and your team!
We all know that useful documentation should cover the basics instructions of how to use tools and its main features. But we also find that, most importantly, your documentation should respond to specific use-cases you find in your workflow. For example, we use Big Blue Button and Jitsi for video conferencing. There are several public resources available about these tools (like this one on BBB or Jitsi’s official FAQ), so our internal guide to the tools are short and straight to the point, covering the main questions our team members have had about them. We always make sure to link to external resources to have as references – because we don’t want to duplicate resources and we also want to avoid having to constantly update our internal documentation every time the external documentation is updated.
Keep it concise and use visual resources
General things we try to keep in mind when creating technical documentation:
- Prioritise visual resources, (like screenshots, drawings and diagrams!) to help make things clearer. There are a few resources online that exemplify how this can be done: the Totem project, for instance, has online courses that include diagrams and images (we like this one on How the Internet works!).
- Avoid long paragraphs of text. When possible, we avoid overly narrating every single detail about the tool. Instead of “move the cursor to the right of your screen to open the menu…”, we try to go for “click on the menu on the right”. If someone needs a more detailed explanation, we make sure they have space to ask, and we offer to host an introductory session.
- Synthesise as much as possible. Usually when we’re reading this kind of document, we’re not looking for long form text. We want direct, quick answers about something we haven’t been able to figure out by themselves.
- Remember that people don’t “read” technical documentation, they skim it. We always try to keep in mind that people usually “scan” technical documents looking for specific answers. Formatting (when used intentionally) can help this process: using bold, italics, colours, creating “warning boxes” can help us highlight what is most important and make “scanning” easier for the reader.
Dealing with technical terms
Sometimes it’s hard to avoid using technical terms that some people might not be familiar with. If it is necessary to include technical words, we try to explain them briefly in context. We find that, depending on the tool, creating a glossary can also be a good idea (see this example from Surveillance Self-Defense!)
Tools change and evolve – your documentation should too!
We try to keep our tech documentation “alive”: team members can ask questions, make comments and suggest edits on the documentation itself (gitbook, which we use, allows this! Other tools do too!). Internally, our team leaves questions on our shared documents about things that aren’t clear and then the Tech Team updates the documentation as needed. This process is important because tools get updated from time to time, which often raises new questions and because the way we use tools may also evolve over time, it’s important that the documentation evolves too.
Make the documentation more engaging
As an attempt to make tech tool documentation a little less boring, we’ve experimented with:
- Adding some encouraging commentary and encouraging tolerance to the frustration of not understanding everything (not understanding everything immediately is an expected part of adopting new technology!). And sometimes, even the support people themselves don’t know everything! 😉
- Using “Question and Answer” formats, to expand on the most common questions that come into technical support.
- Including memes or GIFs (and even making jokes about the retro charm of the interfaces of some FOSS tools!).
Keep it human
Being a remote team that is committed to using justice-based tech tools as much as we can, having documentation about the tech we use is super important to our workflows. But written documentation isn’t everything. We find that having people on the team who we can actually talk to about these tools is super helpful. Other things to try are having “peer-to-peer sessions” to support each other as we learn to navigate new tools, and having live Q&A sessions to address the problems or doubts that emerge when we’re working with something new.
If you’d like to get support from our team, learn more about our work and get in touch to explore ways to work together.
Image by Kvalifik via Unsplash.