Communicating to Users About What We’re Doing
- We give the users a PB&J recipe, assuming they know what we meant when we say “put pb on bread.”
- We leave too many assumptions undocumented.
- Know your audience for the communication.
- How to get feedback?
- People only reach out when things are broken.
- Ask targeted questions, and be open to criticism.
- People DON’T reach out, and instead work-around or walk-away.
- Our-Sci
- creates detailed instructions, and emphasizes the importance of all the steps
- actively checks back with the user in-season
- checks back again post-season
- Which is more beneficial: Documentation or Demos?
- very long docs glaze over user’s eyes.
- videos are useful.
- OpenTEAM working to create dictionary of terms in the space.
- Introducing new terminology (Earth-steward)
- long definition in-line, or move to appendix
- use in-line hover / tool-tip
- Farmer’s aren’t going to read any of this. Only 10 days to plant. Need personal support.
- People often don’t read the manual. Nor do they want to.
- Need to tell the user the big picture “What we’re after, and here’s how I would do it.”
- With researchers as end users, things can go much different than with farmers who are trying to get right out into the field.
- Use personas when writing documentation.
- Need user-base to have sufficient commit to work with you through technical issues.
- Use source code management to keep code and docs in sync.
- ~Notion~ for documentation (links into build systems to update docs automatically).
- Language is key to accessibility.
- When creating tools, be sure to include some example data. Like farmOS, deployments include demo data.
- Friendly forum is a huge help. Reduces the amount of secret handshakes
need to get started.- Sometimes user is in the field with broken equipment, they want an answer now. Outside of business hours, it can be a great help to users.
- Discord and Reddit are frustrating channels for support staff.
- Make your support tickets searchable on google/duckduckgo.
- Explaining open source and open data to users.
- if there is any specter of a chance that data will be harvested, users get very concerned.
- Detailed answer may not be the best route (succinct and decisive is a warm fuzzy blanket).
- “Despite best efforts, it is hard to explain what I’m doing in this space.”
- Just keep trying to explan, and eventually you’ll get the right level of detail for each audience.