Intended audience: DataKind Volunteers
As a reminder, everything about your project should be documented in the Google Drive folder (project plans, meetings notes, etc…) or GitHub page (code and code documentation). As a DataKind volunteer, you are committed to maintaining documentation of your own work.
Documenting lessons learned
DataKind believes we can only succeed if we sustain a culture of constant learning, feedback, and improvement. That’s why it’s so important to document what you learn while working on your project!
-
Have you learned something specific to your project that you want to make sure is documented?
- Talk to the Project Manager about the best place your team is compiling learnings throughout the Execute Stage. There will be an opportunity to share these learnings during the Share Stage, so it’s important to note them as you go! Even if it is something small that you might forget but could be useful for the partner organization to know - act before you forget it and write it down! It’s amazing how small learning can be hugely informative to an organization.
-
Have you learned lessons that could be applicable to others across the DataKind community? Want to share what you’ve learned and contribute to the DataKind community knowledge base?
- If you think your experience would be useful to share, reach out to your Chapter Leaders or DataKind staff support person! Together we can make sure your learnings are shared with people who can benefit from them via updating this Playbook, writing a project case study, posting in a relevant Slack channel, and/or sharing with your Chapter through regularly scheduled calls and engagements. If you’re not sure who to talk to, anyone can always reach out to community@datakind.org to connect on sharing learnings across the DataKind community.
Documenting instructional material
In addition to documenting lessons you learned while doing your project that other DataKinders may benefit from, it is vital to create clear instructional materials for your partner organization so they can actually use the great solution you create! Having clear, easy-to-follow instructions is just as important as the cool data science stuff. Here are some tips for creating effective, user-friendly instructions:
- Invest project time in following this guidance, even at the cost of data science features if necessary.
- Avoid instructions when possible. Most people dislike reading pages of instructions (like this one!), so try and avoid it for your project by…
- Simplify deployment: Move long lists of system commands into one executable script, consider a wizard to ask questions during deployment, guide the user, use central environment variables and macros instead of hard-coding, and reduce system dependencies by using Docker/Kubernetes
- Move instructions to be in-context, where they are needed most: Make error messages human-readable and provide tips on how to fix right there
- Have the system follow the instructions, not the user: If time permits, consider writing a user interface to guide the user so they don’t need …. Instructions!
- Prioritize user-friendliness. Consider that you’ve likely been working with the solution for a long time, but the person reading your instructions might not have any idea what it does. They will likely be incredibly busy and may feel stressed trying to use a new (to them) technical tool. Assume as little background knowledge as possible and link “how to” resources or concept description pages for anything that might be new. Try and think about how clear and concise you’d like instructions to be if it was you.
- Use clear, simple language. If you write a long sentence, think about how to make it simpler. Use screenshots and record quick gifs or videos if this would make the instructions clearer.
- Use clear structure. Use the structure that makes the most sense for your project, whether video, written, or a combination. Always start with a sentence saying what the solution does and instructions are for. If the instructions are long, provide a table-of-contents at the top to help the user get some quick context before starting.
- Test, test, test. It is crucial to have other people test your instructions. It’s very easy to miss documenting one tiny step because you do it automatically, which in turn could hold back a partner for weeks. Test first with a team member, then with your partner at the partner organization, and lastly with someone unfamiliar with the project - if there is turnover within the organization, someone new to the product needs to be able to use it correctly and address a simple maintenance issue. Finally, refine your instructions based on the feedback you gather. You can find an example of some tested instructions here.
- Create a sustainability plan. Instructions are often part of Sustainability Plans for DataKind projects, which also include contextual information to help the organization sustain the product. For example, consider the need to plan for the potential risk that software updates may pose for the tool you hand over and propose pathways for remediation if applicable. See example 1, example 2, and a basic template of a Sustainability Plan.
Contributer(s): Mitali Ayyangar, Benjamin Kinsella, Rachael Blake, Matthew Harris, Michael Dowd, Mallory Sheff, Rachel Wells
Contact us
If you would like to learn more about us, partner with us, or get in touch, email us at community@datakind.org
Subscribe