Documentation/Hackathon 2022 docs discussions
This page captures community feedback from the 2022 Wikimedia Hackathon session "Documentation to Conquer the Dungeon".
Summary of feedback
[edit]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
[edit]Quotes from the session chat transcript and from the collaborative Etherpads we used are aggregated on the Discussion page. Add your thoughts there!