Page MenuHomePhabricator

[Tech docs outreach] Revise and apply guidance for technical documentation "good first tasks"
Closed, InvalidPublic

Description

To support technical documentation outreach and education, it's useful to have tasks in Phabricator that have been written with newcomers in mind, and tagged as "good first tasks". The WMF Tech Docs team has identified a need to:

  • Revisit and refine our understanding of what makes a good first doc task, so that we can
  • Provide guidance for ourselves and others in creating good first doc tasks, and then
  • Use the revised guidelines to collaboratively improve the quality and quantity of tasks in the existing backlog (as of this bug filing, there are only 11 tasks for the "good first docs tasks" query).

Existing guidance:

Event Timeline

TBurmeister changed the task status from Open to In Progress.Apr 10 2025, 4:49 PM
TBurmeister triaged this task as Low priority.
TBurmeister moved this task from Next to In progress on the Tech-Docs-Team board.

Small note related to this task: I have just proposed some revisions to https://www.mediawiki.org/wiki/Documentation/Contribute on the corresponding Talk page.

Status update: Shared my analysis and ideas with the docs team for review and discussion. I attempted to define criteria and a template for good first doc tasks, but encountered some challenges and barriers along the way, which led me to question the feasibility and validity of this effort. So, I outlined my concerns and we will be discussing how to move forward.

After investigating this topic at length, I concluded that it isn't actually feasible for technical writers to put significant time or effort into generating or curating good first doc tasks. The existing guidelines for good first tasks are accurate; the larger issue is that most doc tasks are not good for newcomers, and that the type of expertise newcomers have may vary in several ways that adds complexity to the work of defining what is a good first task. I plan to publish more about this as an on-wiki essay once I've had time to reduce the existing opinion piece I wrote about this in a Google Doc :-) For now though, in the spirit of new fiscal year clean up, marking this task as invalid as per https://www.mediawiki.org/wiki/Bug_management/Bug_report_life_cycle