Documentation/Hackathon 2022 docs discussions



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

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!