Talk:Documentation/Hackathon 2022 docs discussions

How can we help each other to keep going when documentation is frustrating and improving it seems hopeless?

There are always people who feel hopeful when we aren't! It's good to know them and use their reassurance. (Let me put here again my offer of consolations to anyone frustrated by Translate markup – you can always reach out to me.)

Comments from the Hackathon discussion etherpad and meeting chat transcript:

---

Recognize the challenge:

-- "Stay positive! These are hard problems and even small improvements make a difference :)"

-- Remember that the Translate markup / extension are "Really helpful for translators even though it can make it harder to write documentation. "

Appreciate your own contributions and those of others:

-- "Using the "Thank" button." (+1)

-- "Knowing that someone benefits from the work that you've done can be a good way to support yourself"

-- "Badges? "

Connect with each other (social events?):

-- "Depends on introvert vs extrovert"

-- "Yes.  They are fun and point me in new directions. Working with others who have questions and answers can help make it doable to improve or document."

-- Comment on Phabricator tasks

-- Tackling writer's block "I'll find someone to bounce ideas off of until something about the interaction sets off a spark of "Here is another angle" or "Here is another structure" or "This is the core problem with what's going on" which then gives me an angle to tackle."

  A. What can make writing (or updating) technical documentation difficult for you in general?

  B. What unique aspects of the Wikimedia ecosystem can make writing (or updating) technical docs difficult?

  C.  Is there a type of challenge that you feel you encounter more than others when trying to improve documentation?  How have you dealt with it in the past?

Comments from the Hackathon discussion etherpad and meeting chat transcript:

---

Too many docs:

-- "For newcomers, documentation can seem a bit hard, there's not a clear path to follow, you just come across a lot of information that makes you want to close everything and run". +1000

-- "Too many docs that need to be merged and overhauled"

-- "Information organization is massive. Wikimedia's core documentation problem is the pile of spaghetti problem. There's thousands and thousands of pages and no "start here and do these things in this order to learn what you're doing well enough"

Not knowing what to explain or how to explain it; hard to get started:

-- "Not having enough of a grasp of the situation and environment to be able to make the thought stream linear and clear." (+1)

-- "Lots that I don't know, and can't explain; but I can find some things to link to on-wiki"

-- "Distinctive environments where I've got MediaWiki installed, outside the WMF platforms, and problems that might be peculiar to those environments.  I don't know the breadth of interest in my distinctive problem"

-- "There's too much out there and no on-ramp and no one to ask for guidance and no path to learn"

-- " Everyone has so much going on, so I agree that by wanting to respect everyone's time, it's just hard to find guidance if you want to make some changes and have no idea where to start."

-- "on the topic of seeing no entry point into Wikimedia ecosystem: there is indeed none, and there is no handout "these are all the basic things you need to know", because there too many things to be known. however! one can navigate the system in their own way, not having to learn everything that others know. it is possible to be extremely useful without ever using Phabricator, etc. I honestly believe it."

-- "In other contexts I am really good at translating tech to human. I do not have enough of a handle on anything to be useful yet. I need an on ramp that I have not yet found."

-- "No one to explain what's going on or whom it's significant to or how to get started"

Publishing process complexities / translation:

-- "Wanting to respect the time of translators by making sure docs are as good as possible before marking for translation"

-- "Once a document has been set for translation, I think it may discourage users who would like to edit the original language version"

-- "Multilingual collaboration [is] difficult. Sometimes documentation is incomplete, but once a language has been chosen as the "official" language version (usually English), people who would like to expand the documentation are obliged to doing it in English. I guess that's a problem difficult to tackle anyway."

-- "At the beginning I was hesitant about having one single issue tracker for everything. I felt too exposed. But then I got used to it, and now I like it."

What resources do we have to help us improve and maintain Wikimedia tech docs?

  A. What makes writing (or updating) technical documentation easier for you in general?

  B. What tools make writing (or updating) docs harder?

  C. What tools or resources do you think are (or would be) especially helpful for Wikimedia documentation?

  D. What tools have you tried to use in the past, but found unhelpful?

  E. What tools have you seen used in other settings that you think we should try in our community?

  F. What resources do we have the most ability to leverage as a community? (consider the categories of people, technology, and time)

Comments from the Hackathon discussion etherpad and meeting chat transcript:

---

Important resource: other humans:

-- "Having a human with a high skill set explain the technical depths to me so that I can translate it for the people a step or two behind me in the tech comprehension level"

--"Human to human reference points"

-- "Train the trainer" teaching sessions from Software Carpentry helps people level up their skills and get connected to people with expertise

-- "How I conquer writers' block is by recognizing the signs and knowing what it means about what's going on. If I start feeling blocked I know it's because I haven't got enough of a handle on either the problem or the way to smooth the sequence to a solution, and I'll find someone to bounce ideas off of until something about the interaction sets off a spark of "Here is another angle" or "Here is another structure" or "This is the core problem with what's going on" which then gives me an angle to tackle."

Useful tools: content metadata; collections; doc lists:

-- "Clear indication of how up-to-date a page/section is."

-- "Clear hubs listing out the most useful and current docs. E.g. https://www.mediawiki.org/wiki/Documentation is good."

-- "Is there an equivalent of a Featured Article for documentation? Can there be?" +1

Useful tools: templates:

--" Big wikis will have documentation for creating a template. It helps to have a wireframe to get started."

-- "Anything that makes it easier to balance static and dynamic content - templates, etc"

Useful tools: translation:

-- "New Visual Editor support for translation markup https://diff.wikimedia.org/2022/05/12/mediawiki-1-38-brings-support-for-editing-translatable-pages-with-the-visual-editor/ "

Different formats for communicating information:

-- "In a project we are developing (Web2Cit) we are finding it hard to start writing documentation. As a compromise solution we've found it useful to record technical videos (recorded talks + Q&A), like our software architecture video. We understand it may be more difficult to keep it up to date, but we like that at least it is something. On the other hand, sometimes having an introductory video to something complex as software architecture may be useful for newcomers to the project."

Not helpful:

-- "Sitting down with a pile of documentation has been completely unhelpful to me - "read the man pages" has never worked for me over 20-some years because it's written half in programmer and despite 8 programming courses I still am not a programmer"

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)."

A. What can make writing (or updating) technical documentation rewarding or worthwhile for you in general?

B. What unique aspects of the Wikimedia ecosystem can make writing (or updating) technical docs worthwhile?

C.  Is there a type of documentation contribution that you feel especially good about making?

Comments from the Hackathon discussion etherpad and meeting chat transcript

---

Helping other people, especially newcomers, have a better experience:

-- "Making the on ramp less terrible (or make it actually exist) for the people who come after me"

-- "That it might get better or easier for other people in the future"

-- Helping people who are "looking for starting points to enter into the documentation"

Improving the overall health of the system

-- "so by modifying or contributing to technical documentation, it's a long-term goal towards having a "better system" I guess." (+1)

-- "Making things easier for my future self" (+1)

The challenge and fun of translating tech to human

Making content more correct (https://xkcd.com/386/ (Duty Calls))

Helping increase understanding by adding simple clarifications:

-- " I feel good about adding simple clarifications to installation instructions on mediawiki.org.  We can wikilink to some explanation of unexplained things (PCRE? what's that?  replace by [[PCRE]]) or clarify what directory a script should be run from, etc. "