Page MenuHomePhabricator

Determine how to make doc assessment data and priorities into tasks
Closed, ResolvedPublic

Description

This is a tracking task for work related to the second half of our Q1 2022-23 objective to "Make it easier to assess the state of documentation and contribute meaningful improvements." In the first part of that objective, we seek to "Identify documentation collections and how to assess the state of the content they contain. "

This workstream focuses on how we should Make the results of this assessment publicly available and easy to navigate. In other words, what is an effective and sustainable way to enable the entire community to assess docs, identify priorities in sets of docs that have already been assessed, and find (or create) clearly-scoped doc tasks that enable meaningful and rewarding work on doc improvements?

Link to workboard for this sub-project: https://phabricator.wikimedia.org/project/view/6034/

Event Timeline

Tidbit from T156301:

Having a group in charge of triaging / grooming the Documentation workboard, identifying top priorities, and organizing activities (including lobbying to the Wikimedia Foundation) in order to complete the top priorities... that would be already a huge step.

...but I think we new tech writers will need a bit of a history lesson on how this went from "Getting a Documentation SIG up and running is currently part of the Technical community building program in the FY17/18 draft annual plan for the Wikimedia Technology department", to "Technical Document Re-working Group", to "Friends of the Docs" which is on hiatus due to being under-resourced and due to the departure of srodlund. Just noting all of this here because our work this quarter is learning about past efforts in hopes that we don't repeat past mistakes, or can at least be informed by them as we engage in new exciting mistakes of our own!

TBurmeister triaged this task as Medium priority.

...but I think we new tech writers will need a bit of a history lesson on how this went from "Getting a Documentation SIG up and running is currently part of the Technical community building program in the FY17/18 draft annual plan for the Wikimedia Technology department", to "Technical Document Re-working Group", to "Friends of the Docs" which is on hiatus due to being under-resourced and due to the departure of srodlund.

My TL;DR for all of this is that we (mostly Sarah R and myself) had grand hopes during multiple annual planning cycles that building a new sub-community from scratch would work, but that in practice we never made enough space to do the very large amount of outreach work needed to get things working. We allowed ourselves to think mostly about the good that a functional wiki project like community could do without putting in enough tactical planning work to actually bootstrap such a community.

An example from 2018 of an RFC related to documentation that was not well received and didn't seem to achieve its goal of eliciting feedback about which documentation various audiences need to achieve their goals: https://www.wikidata.org/wiki/Wikidata:Requests_for_comment/Improving_Wikidata_documentation_for_different_types_of_user

Developer wishlist project/process had a section for documentation that received more engagement about doc priorities than
other types of RFCs, but still minimal engagement given the size of the developer community overall: https://www.mediawiki.org/wiki/Developer_Wishlist/2017/Documentation

Process proposed by User:Zakgreant is based on the idea that "design a process that consists of many small steps that can be done independently of each other. Each small step should be relatively quick to complete and should improve the documentation in some meaningful way. The steps should move the documentation cleanly from state to improved state. "

At a very high level, the recommended process has two steps that are repeated over and over:

Contribute something new or an improvement to a flagged page
Review contributed work and flag one or more issues with it
The process splits the work of evaluating the documentation from the work of improving the documentation. This split exists because it makes it easier for people to contribute in small, but still meaningful, pieces while they are doing other work. It also allows people to focus solely on tasks that interest them – if someone wishes to only write examples, it should be easy for them to find everything that needs an example.

The brief overview above is very, very abstract. Here's an example of how this could work in practice:

D. E. Veloper is hacking on the MediaWiki internals and encounters a mysterious global variable called $wgSurprise.
D. goes to the MediaWiki.org and searches for wgSurprise.
The search engine returns a few results.
Looking at the first result, it seems to provide D. with most of the information that they need.
However, the page has an incomplete summary and doesn't follow the standard template used for global variable reference pages.
D. flags the page as having a deficiency with its summary and then returns to hacking code. (Note: The flagging could happen via any number of separate mechanisms – let's leave the exact mechanism aside for now.)
With enough time and interest, D. might have done other bits of work, including:
flagged the page for not using the standard template
using checklist to see if the page had other issues
worked on fixing some of the issues that they encountered
fixing that other people have flagged
Later, another person – Doc Umentor – after looking through a list of flagged pages that need work on their summaries, comes along and improves the summary for wgSurprise.
When Doc is done with the improvement, he saves the page and removes the flag.

Questions people asked at Docs Q&A at 2021 hackathon indicate some important areas of uncertainty to address in any doc contribution process, to prevent people from leaving due to fear or lack of clarity around these issues:

  • Where can we fill in the gaps? (how should I direct my energy? -- that is sorta the main question of this phab task)
  • Should I add missing information if my language skills aren't fluent? (yes)
  • Should we delete outdated pages? (yes)
  • What about pages that are partially obsolete? (Remove outdated content. Bias towards simpler pages with less content. Versioning allows us to document behavior in past versions. )

For hackathons and synchronous events, a common format for coordinating doc tasks has been identifying areas of doc work (sometimes spanning multiple phab tasks), posting them on a wiki page with a brief summary of what should be done, and having a space for people to sign up to work on them. This seems like unnecessary overhead that could be entirely done in Phabricator and summarized on-wiki afterwards (maybe?)

Examples:
https://www.mediawiki.org/wiki/MediaWiki_Documentation_Day_2017
https://www.mediawiki.org/wiki/Write_the_Docs_San_Francisco_Meetup_May_2017 (most tasks here seemed very large...)
https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons

This seems like unnecessary overhead that could be entirely done in Phabricator and summarized on-wiki afterwards

Big +1. In the past I removed a bunch of Phab tasks listed on https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons but that page should not exist at all as it simply gets out of sync. It should be 1 link to a list of tasks in Phab, e.g. Documentation && good first task && open status, or such.

TBurmeister changed the task status from Open to Stalled.Oct 24 2022, 5:51 PM

I am working on the overhaul of mw:Documentation, but we weren't able to complete this task in Q2, and work focused specifically on how we manage documentation tasks (inside or outside of Phabricator) wasn't prioritized for Q3. Tech writers will be reviewing and cleaning up phab tasks with the documentation tag for the projects we focus on this quarter, but other work will have to wait.