Documentation/Hackathon 2022 docs discussions

This page captures community feedback from the 2022 Wikimedia Hackathon session "Documentation to Conquer the Dungeon".

Presentation slides from documentation discussion and talk at Wikimedia Hackathon 2022

Summary of feedback

Documentation challenges:

• Too many docs
• Not knowing what to explain or how to explain it; hard to get started
• Publishing process complexities / translation

Benefits and motivators for improving docs:

• Helping other people, especially newcomers, have a better experience
• Improving the overall health of the system
• The challenge and fun of translating tech to human
• Making content more correct (the joy of being right on the internet)
• Helping increase understanding by adding simple clarifications

Documentation tools and resources we can use:

• Important resource: other humans and their knowledge
• Useful tools:
  • Content metadata; collections; doc lists
  • Templates
  • new Visual Editor support for translation markup
• Different formats for communicating information (video, not just text)

What helps us keep going even when it's hard?

• Recognize the challenge
• Appreciate your own contributions and those of others
• Connect with each other (social events?)

Documentation strategies to emphasize:

• Working in collaboration with others (mentors, people with shared interests)
  • Leveraging different experience levels (a non-expert reading docs written by code author may have crucial insight to make docs more understandable and avoid the curse of knowledge)
  • Better/unified communication channels to ask docs questions
• Tightly-scoped or bite-size tasks and checklists
• Docs live with code and are updated with code changes
• Promote standard cleanup templates

More details

Quotes from the session chat transcript and from the collaborative Etherpads we used are aggregated on the Discussion page. Add your thoughts there!