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