Session: Communicating to End-Users

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
    1. creates detailed instructions, and emphasizes the importance of all the steps
    2. actively checks back with the user in-season
    3. checks back again post-season
  • Which is more beneficial: Documentation or Demos?
    1. very long docs glaze over user’s eyes.
    2. videos are useful.
    3. OpenTEAM working to create dictionary of terms in the space.
  • Introducing new terminology (Earth-steward)
    1. long definition in-line, or move to appendix
    2. use in-line hover / tool-tip
    3. 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.
    1. 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.
    2. Discord and Reddit are frustrating channels for support staff.
    3. Make your support tickets searchable on google/duckduckgo.
  • Explaining open source and open data to users.
    1. if there is any specter of a chance that data will be harvested, users get very concerned.
    2. 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.”
    1. Just keep trying to explan, and eventually you’ll get the right level of detail for each audience.

@sezuco Thank you for facilitating!