Outcomes of the documentation session at the ODK convening 2019


Discussed by Dickson M, Maaksi, @KeynesYouDigIt, @Alba, @Florian_May

ODK = ODK & ODK-X & friends

Suggestions for improvements to docs:

  1. The undecided not-yet-an-ODK user wants to know whether ODK (or a combination of ODK components) can provide a solution to their electronic data capture problem.

Suggestion: add a showcase of curated ODK success stories e.g. presented as gallery of cards, each linking to a sexy one-pager with pictures and diagrams of solution architecture and more information.

Benefits go three ways:

  • Sleekest way to tell the user whether ODK is a fit for their problem
  • Attribution for show-cased projects
  • Bragging rights for ODK

Prototype mock-up https://kind-yalow-42adff.netlify.com/

  1. To the committed but inexperienced ODK user, navigating the docs is hard and possibly confusing.

A top level diagram of ODK components (Build, Aggregate, etc), possibly split into swim lanes of [form design, data capture apps, data clearinghouse, etc] with links to relevant subsections would be a great visual entry point.

  1. I'm stuck! Now what?

FAQ. Searchable. Linked from everywhere a user might have a question.
The friendly switchboard for ODK users having a problem/question/request to find the appropriate silo (webpage, docs, github, forum, slack, youtube channel).

  1. I don't like to read. How does everything work again?

Youtube videos.

  • Marketing: the elevator pitch.
  • Tools: the 5 minute whirlwind tour.
  • Specific problems/features: how to do X.