Jump to content

Topic on Talk:Documentation/Hackathon 2022 docs discussions

Documentation tools and resources

2
TBurmeister (WMF) (talkcontribs)

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)

TBurmeister (WMF) (talkcontribs)

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"

Reply to "Documentation tools and resources"