GOSH Community Forum

Day 2: Documentation Guidelines

Attendees

@mkdryden @mattr @mariafrangos @nicole

Summary

  • Discussed general guidelines for documentation
    • Survey to collect more information
  • Some general frustrations and solutions for reducing documentation tedium

Notes

  • Guidelines for documentation
    • Just because a project is freely available, does not mean it is accessible
    • Too many different circumstances to have a single documentation standard
      • e.g. academics, hobbyists, areas with low literacy, areas with poor internet access
    • Good documentation practices help encourage collaboration and uptake
    • Survey to collect information to produce guidelines
      • Want to know what kind of documentation builders need, common issues, barriers to accessing and using documentation, etc.
      • Want to know about developer concerns: What factors keep developers from making good documentation?
      • French translation would be good
        • Workaround Use built-in page translation in Chrome browser
    • Labeling system
      • Help people assess difficulty, skills/tools needed, etc.
      • Considering regional requirements
    • How to keep guide itself accessible
      • Translations, other accessibility issues
  • Documentation is tedious to produce
    • Ways to automate documentation
      • Automatic translations
        • Keep language simple to help translations
      • @mariafrangos has feature ideas for opencapture.io app (owns domain)
        • Easy way to capture documentation while working
        • Manage projects
        • Tools to help people adhere to documentation guidelines
    • Simpler documentation solutions can reduce barriers
      • Easy things like taking photos with a phone app
    • Photos in documentation are more effort to keep up to date
    • Some projects are in active flux, so documentation is playing catch-up
  • Barriers to adoption of projects
    • Lack of information can prevent adoption of an open science tool
      • More risk when documentation is unclear

Action Items:

  • Attendees will disseminate survey widely and review results
  • @mariafrangos discussing with developer about opencapture app