Topic on Talk:Documentation/Hackathon 2022 docs discussions

What strategies might we use to help us write and improve Wikimedia technical documentation?

  A. Do you prefer to be given tasks to complete, or to be taught how to identify those tasks yourself? Maybe both?

  B. Do you prefer to identify and solve problems in collaboration with others, or independently? Maybe both?

  C. Do you prefer to fix small issues as you encounter them, or focus on making more holistic improvements in one area at a time? Maybe both?

  D. What strategies do you think are (or would be) especially helpful for Wikimedia documentation?

  E. What strategies have you tried to use in the past, but found unhelpful?

Comments from the Hackathon discussion etherpad and meeting chat transcript:

---

Working in collaboration with others (mentors, ppl with shared interests):

-- I prefer to be given a mentor whom I can collaborate with while learning the ropes. I do my most effective and efficient work when given a task by someone I can work with. (+1)

-- "Definitely in collaboration" (+1)

-- " Collaboration is definitely for me"

-- "Help people with particular interests find one another.  I know this is off-topic but I am now documenting tax administrative details of being a proper not-for-profit Wikimedia chapter in the US. Should you file form 5768, for example?  Why?  I know this is not called technical documentation but it's similar.  If we find one another we can document some things together."

Tightly-scoped or bite-size tasks and checklists:

-- "It depends on the scope of the problem. Small bitesize issues are good for getting feet wet, but without a large grasp of the entire system you can't have the perspective for holistic improvements, and there needs to be a way to get across that gap"

-- "I think tasks are very important to work like this and I like the idea of a checklist. Maybe seeing documentation as a mega-project filled with small tasks can help us to make problems visible and tackle them better."

-- "A checklist of bite-sized chunks is helpful for getting started making improvements"

Strategies: docs live with code and are updated with code changes:

-- "Importance of having documentation live with the code, so it can be integrated with continous integration to remind developers to update the docs."

-- "In an ideal world, documentation would be written by people who wrote the code.

--> Counter: Helpful to have an outside perspective

--> Actually Wikipedia works partly because person A may be able simply and clearly explain some basics of the advanced work that person B is doing, whereas B would get caught up in the details or hard cases or conflicts with others. This is common in sci and tech I believe.

-- * Related to this - how can we sync with other documentation-adjacent tools programmers use on a daily basis - Git/Github, Markdown, javadocs, etc - might there be a way to integrate these more closely?"

-- "Accountability processes: How to keep people accountable for updating documentation when code is updated?"

Strategies: promote standard cleanup templates

-- "Wider usage of the specific cleanup templates, e.g. https://www.mediawiki.org/wiki/Documentation/Style_guide/templates "

Strategies: doc support channel(s)

-- "A clearer location for docs-specific questions (Q&A). There are E_TOO_MANY_TALKPAGES to choose between, many of which are unwatched (by the 'right' people)."