User:TBurmeister (WMF)/Good first doc tasks

This essay captures my opinions about good first tasks for technical documentation. It's based on several months of research, my experiences working with the Wikimedia technical community (including newcomers) at hackathons, and my attempts to curate good first tasks specific to technical documentation work. In Q4 of FY 24-25, this work was tracked in phab:T391608.

Motivation

FOSS projects often list technical documentation as a good first task for new contributors. The (perhaps flawed) reasoning behind this seems to be that editing docs is easier than writing code, but can familiarize newcomers with the codebase and tooling required to eventually make code contributions. Wikimedia hackathons and other technical community events often seek to include technical writing tasks or documentation tracks as part of the programming. As one example: the 2025 Wiki Mentor Africa Hackathon had 150 participants who expressed interest in working on technical documentation.

When I started work on this project, there were only 11 technical documentation tasks labeled as "good first bug" in Phabricator. The existing guidance for filing documentation tasks didn't contain many specifics about good first tasks. I wanted to see if I could define criteria that would help us grow the backlog of good first documentation tasks, because I thought that would help us better engage newcomers at hackathons and beyond.

Project goals

I started this investigation based on the assumptions that good first tasks (GFTs) can help:

• Grow the community of technical documentation contributors by providing a pathway to build confidence as technical writers, and get familiar with Wikimedia technical projects.
• Improve tech docs.

When I began, I already knew that a GFT should be simple and focused, and have a clear target audience. And, I knew that very few docs and topics in the Wikimedia space meet those criteria. Still, I had hope! So, the original goal of this project was to:

• Create guidelines and criteria for "good first doc tasks" for tech docs in the Wikimedia context.
• Define the information that should be included in the task description.

I did some work on both of those things, but…I can't recommend it. Why not? Read on!

🔥Hot take

My work this quarter has convinced me that we probably can't pursue both growing the community of doc contributors and improving tech docs through the same tactics, if by "growing the community" we mean onboarding newcomers who have no experience with Wikimedia nor with tech writing. The next few sections explain the major challenges and assumptions I encountered that led me to this conclusion and my ideas for how to move forward.

Multiple audiences and extra complexity

One of the first criteria I drafted for good first tasks was that they should define an audience. This immediately led me to the issue that prospective contributors can be "new" to different aspects of tech docs work, and that makes it difficult to write a single definition of a good first doc task.

The audience of GFTs in the development context of an open source project is clear: people who are unfamiliar with the codebase and want to contribute code. They might be new developers, or they might be experienced developers who are just new to the project. They are likely using a standard set of development tools and workflows to create their first patch.

When I started to consider the different ways someone can be a newcomer to Wikimedia technical documentation, I realized that the complexity of our context impacts even this fundamental task of defining a single audience for this work. We would potentially need to define different GFT criteria for subsets of these audiences, because it's unlikely that a GFT for one subset would also be a GFT for another:

This is a terrible diagram, but I hope the point is clear: doc contributions have more axes of complexity than code, especially in the wiki context.

One of my case studies actually has a GFT framework that could help with this, but before we get to that: there are more issues.

Assumptions likely false!

As I explored this topic, I was simultaneously working on trying to expand some of our doc review checklists to make them cover more aspects of doc quality, but without making them too complex for non-writers. These parallel efforts helped me realize that some of our foundational assumptions might be incorrect, or at least unproven:

• Assumption: Curating a robust backlog of good first doc tasks is possible. This assumption is not yet proven, and the research summarized here provides some evidence it may be false.
• Assumption: Curating good first doc tasks is worthwhile. Even if it's possible, is it worth the time and resources required to curate a backlog of GFTs specific to tech docs? My investigations provided a clearer idea of the work required to curate GFTs: it's a lot. So, this assumption seems likely to also be false...depending on prioritization decisions.

🔥Hot take

Curating relevant and feasible GFTs would require close collaboration between tech writers and developers. We need developers for the subject expertise, and they need us to identify the doc improvements. The amount of effort and collaboration it would take to curate those types of impactful and meaningful GFTs would be better spent by tech writers just working with developers to improve the docs. It's an entirely different project, but maybe the WMF Tech Docs team should prioritize teaching people excited about writing how to collaborate with developers, instead of focusing on curating a backlog of GFTs.

Challenges and barriers

To enable contributions (at any level) to Wikimedia tech docs, we need to be able to communicate two things:

• What contributions do we need? Which docs need work, and what type of work do they need?
• How can people contribute? What is the process to contribute, what tools must be used, how can a contributor know their contribution is valid and successful?

The ability of our team, or any development team, to understand and communicate both of those things simultaneously, in the form of a Phabricator task, is hindered by two types of challenges:

1. The nature of technical writing work.
2. The broader Wikimedia context.

Allow me to take you on a tour of these dragon lairs. 🐉☠️

Nature of tech writing work

Doc work may not be divisible

For developers, good first tasks are "small isolated changes that minimize the effort needed to make the change while still requiring the contributor to set up a complete development environment."

Compared to development work, doc work is often more difficult to break into discrete tasks or modular units. Words and sentences can't be taken out of the context of the page, and you can only make a limited set of doc improvements if you focus on a page in isolation, outside of the larger context in which it lives. Unfortunately, the types of doc improvements that are quick, easy to find, and require minimal expertise to fix (all the criteria for GFTs) are the least impactful:

An unfortunate inverse relationship

I think the same is probably true for code…but I think it's more true for docs, because written language is even less modular than code.

Doc skills are harder to self-identify

In addition to the assumption that we could break doc work into discrete units, the GFT approach has another built-in assumption that may not apply for docs: that prospective contributors know their documentation-specific skill level and interests, and can use that knowledge to pick tasks. This assumption is much more likely to be true in context of open source development: it's easier to self-identify as a "beginning Python coder" or an "advanced front-end developer" than a "beginning prose editor" or an "advanced tutorial creator" – those just aren't ways that people describe documentation work and writing roles. Here is one early attempt I made to define different types of doc contributor roles: the audience liked that it was cute and nerdy but we never tried to operationalize the ideas, and I don't think we should…they were based on my worldview when I was very new to WMF, and they represent a pretty complex mental model that would be difficult to communicate consistently when operationalizing.

Doc work is often too complex to be covered by written instructions

Even if the work can be broken into discrete units, the knowledge and judgment required to do that work may not be so easily delineated. I began this project thinking it was worth putting time in to figure out which subset of work could be delineated and worked on by people new to docs and new to our codebase, but given all the other issues outlined in this doc…I'm not so sure anymore. We started to discuss this when reviewing work on phab:T391271, which proposed changes to our doc review checklists.

In reviewing case studies where projects provide extensive written instructions to guide technical documentation contributions, I've started leaning more towards avoiding doing this. I don't even want to read this stuff, and it's my job! It's so overwhelming, I wouldn't want to try to make a doc contribution if I didn't already know this stuff.

• MDN has a lot of written guidance about how to write docs (both for their project and in general)
  • https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
  • https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Write_an_api_reference
  • https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Research_technology (imo this doesn't actually enable a reader to do this very complex task)

The Tech Docs team hasn't explicitly agreed that we should prioritize writing and maintaining this type of educational content, at this level of detail. In general, we seem to lean towards thinking we shouldn't do that, but we need to discuss more. This is part of why one of my key recommendations is about prioritization decisions.

Wikis are optimized for quick fixes

All the actually easy work can be done in less than the time it would take to file a bug. What's left is too complex. This was also noted as an issue with GFTs by a core doc contributor for the Fedora docs.

As another example: the Mozilla Developer Network (MDN) content issue tracker shows 3 open "good first issues" out of 367 issues. I found 487 closed "good first issues". My opinion about these issues is that many of them are so small that in a wiki, the issue reporter could just make the change in the same amount of time it takes to file an issue. Or, if the issue reporter doesn't know the correct action to fix the issue, it's no longer a GFT. That doesn't necessarily mean we shouldn't create GFTs anyway: as eloquently noted by Apache:

The point of the “good first issue” is that it is an investment in future contributors, and, thus, in the sustainability of the project. While it would, indeed, probably be easier to fix it yourself, investing the time to document what needs to be done, and how it might be done, is a way to engage a potential new contributor.

Broader Wikimedia context

Large, opaque backlog and changing organizational priorities

Imagine we have a great list of criteria for what makes a good first doc task, and we want to curate a nice backlog. Where would we begin? Which projects or tags in Phabricator should we look at to try to identify doc tasks to break out? Which teams would we need to talk to? Maybe we could use some of our new doc tools to help, but which pages should we even put into the tools, and would we mostly be identifying work that doesn't meet our criteria?

The effort of tech writers curating a backlog from the existing backlog seems insurmountable. I think dev teams themselves are the only ones who can do it, and it may only be feasible to try to get teams to file GFTs going forward, not backward. But that would likely require a huge culture shift, and probably tech writer-led campaigning and education of dev teams.

Code stewardship, and maintenance of issues in Phabricator, hasn't always kept up with the changing structure and priorities of WMF engineering teams and the technical community. Consequently, looking at a random issue or a doc often requires domain expertise to determine if it's still relevant and worth prioritizing. The issue of churn in code ownership also impacts any backlog of GFTs we might curate: we don't have the capacity to continuously curate the backlog to reflect whether the tasks are for an owned or maintained component. So, that may impact the relevance of the work and result in poor contributor experience.

Lack of resources to ensure positive contributor experience

Social dynamics and communication matter, and they impact contributor retention. Like many open source projects, the Wikimedia movement has some challenges in these areas. As a small team, the Tech Docs team lacks the ability to continuously provide high-touch guidance or mentoring for contributors. Is it worth putting in tons of effort to attract and onboard new docs contributors if we can't ensure their contributions will be welcomed? Theoretically, if a maintainer adds "good first task" to an issue, they're saying they welcome the complexity that comes with collaborating with newcomers, but what if someone else tags a task for your project with "good first task"? Without extensive outreach to maintainers, we can't ensure that doc contributions will be welcomed in a given project, especially if the contributor is new to writing or new to the wiki context and makes common beginner mistakes.

Without proactively curating Phabricator tasks, we can't verify that tasks tagged as GFT are appropriately scoped. Even if we have a nice task template and guidelines, we can't ensure people will follow them. Then, if we're doing outreach to newcomers, we end up pointing them at tasks tagged as "good" that are actually quite "bad" for them. Maybe this is just something we have to live with?

Research has shown that open source contributors are more likely to stay if they have positive social interactions and are not just completing a task in isolation. Are we (or are dev teams) willing and able to provide the mentoring and engagement that would make investing in GFTs worthwhile?

Both tech writers and SMEs at WMF may not have time to reply quickly to unplanned doc contributions and requests for review. Should we try to build that capacity before we put effort into curating doc tasks targeted at newcomers? Review takes a LOT of time. Recent example: ~3 hours to review and provide feedback for one new contributor's work on one page. This process and the changes that came out of it were valuable and worthwhile, but it's important to be realistic about the amount of time investment required.

Background research and case studies

The general idea around good first tasks (or good first bugs) in open source projects is: helping people identify tasks that align with their skills and interests can help ensure success and sustain motivation. This is a common and often recommended tactic in open source coding projects. Despite the ubiquity of the GFT approach in open-source, some research has shown that these types of onboarding programs are actually not very effective.

The following case studies capture the only examples I found of the GFT technique being used specifically for tech docs, and key takeaways from my research into them. There's more background research in the Appendix.

Case study: Mozilla Developer Network

In 2015, Mozilla Developer Network (MDN) claimed that the GFT approach helped them achieve a 46% increase in active editors for their technical documentation. It's interesting, however, that in the same year a paper that researched Mozilla projects concluded that GFTs (not specific to tech writing) don't help retain new contributors. The paper concludes that mentored tasks work better, but only if there's also intrinsic motivation on the part of the newcomer (if no intrinsic motivation, they don't stick around after mentoring is done).

Regardless of this conflicting information, I investigated the MDN docs approach (both past and present) to GFTs. As reported in 2015, they broke doc tasks into two categories: "I like words" and "I like code" (see 10:49 in the this presentation).

Of all the approaches I've seen, I like this one the best! I like that it breaks out work based on two of the major audience types who may be new doc contributors, but I'm a little unsure about the feasibility and time estimates for the actual tasks. As of 2025, that guide is no longer online, and seems to have been replaced by a more generic entry point that leads to a contributing guide, which focuses only on how to submit doc contributions, not how to figure out what to work on.

MDN's issue tracker shows some evidence of an experiment to tag issues with doc quality goals.

Case study: Fedora

I'm including this more as a counter-example. This community has clearly made valiant and repeated attempts to enable doc contributions, but I mostly found seemingly unmaintained lists or categories of tasks. One of their core doc contributors summed up their thoughts about GFTs as follows:

If we were to go looking for “easyfixes” - I am certain to find at least hundreds of those strewn across a variety of projects belonging to a bunch of SIGs, teams, subprojects etc. The thing is, most of the time, it is either deemed unnecessary to mark them out as issues as they are so self-contained that one could solve them over coffee or so unimportant that they are left open like a low-hanging fruit for many years. Having these shown up in a primary place would not make a good look for us is what I am going to say.(emphasis mine)

Examples of Fedora's doc-focused onboarding materials:

• https://whatcanidoforfedora.org/en#writing
  • https://fedoraproject.org/wiki/Join_the_Docs_Project
  • https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/
  • https://fedoraproject.org/wiki/Category:Docs_Project_tasks#Content_tasks
• https://fedoraproject.org/wiki/Wiki_gardening_tasks

Ideas for how to move forward

Given all of the above, how can the WMF Tech Docs team support new doc contributors?

Make explicit prioritization decisions

• Make an explicit prioritization decision about how much time and resources we will put into outreach and education. Building a culture of documentation is one of our team's goals, and we believe strongly that community outreach and education is part of that. Over the past few years, we've gained more insight into how much effort this type of work requires. I also got more experience with that as part of this project, in my sub-task focused on trying to identify good first doc tasks for tools. I think we need to either carve out more time for this work, or consciously decide not to do some of these things. These decisions likely apply to the following types of work:
  • Mentoring: either ongoing, time-bound (like Outreachy), or event-specific (like Wiki Mentor Africa)
  • Education: creating and maintaining resources that instruct about technical writing and best practices, like the Documentation Toolkit.
  • Outreach: proactively seeking opportunities to do mentoring and education, and reaching out to dev teams to promote tech docs best practices
• Be even clearer about who we're trying to support: new writers who are already familiar with our codebase? People completely new to Wikimedia? Experienced writers who could be self-directed if only they had SME collaboration?

Invest in project-specific mentoring and outreach?

If we decide to prioritize outreach and education more strongly, we could do the following instead of focusing on GFTs:

• Focus on doc projects (not tasks) that include mentoring. Basically like Google Season of Docs (RIP) but for our own dev teams and software projects.
  • This is significantly more effort, and scoping is always hard, but experience has shown it to be both successful (positive experience for participants and reasonably impactful doc outcomes).
• Create guidelines for identifying and creating "mentored doc tasks" for docs work which is not simple, focused, etc. but could still be done by a new contributor if they had support.
  • As described above, most Wikimedia doc work doesn't fit the criteria of "good first doc task". But, we could provide a mechanism for project/product owners to still be able to work with new doc contributors if they're willing to provide SME guidance, and we can provide high-touch technical writing guidance.
    • Warning: there would need to be accountability here, and I'm not sure our dev teams could provide that given all their other priorities. In some cases, even WMF tech writers working on agreed-upon projects with SMEs have had trouble getting consistent engagement from devs, so we wouldn't want to put a newcomer into that situation. Maybe we could start with the projects listed on New_Developers or https://developer.wikimedia.org/contribute/by-language/, since those projects have at least committed to providing mentoring, they're just missing the docs focus.

• Explore providing documentation-specific contribution guides (not necessarily GFTs) at the individual project level instead of the meta- level? Examples:
  • Codex has a robust contributing guide with specific sections for design and dev, could easily also cover the types of doc tasks they list among their desired contributions
  • Fedora has some contribution guides by doc type, but they kinda devolve into templates and overwhelming general guidance.

Invest in skill-specific outreach?

We could reduce some of those overwhelming "axes of newness", and avoid the need to create copious amounts of written guidance, if we specifically did outreach to people who already understand technical writing and its best practices.  We could try to grow the community of technical writers by specifically doing outreach to technical writers. The problem? Most tech writers don't want to do tech writing in their spare time. Maybe grad students in technical communication programs? This goes back to: so much effort required, and uncertainty about providing a good volunteer experience.

More proactive Phabricator curation?

Rather than focusing specifically on GFTs, we could direct our efforts towards trying to make more documentation tasks well-defined and clearly-scoped.

• Do outreach to teach developers how to file good doc tasks.
• Develop team processes around, and put more time/effort into proactively curating Phabricator tasks filed by others and tagged with documentation?
  • Revise task descriptions, use a subset of the task template I started drafting?
  • Decline or break up badly scoped tasks?
  • Boldly decline tasks that are unfinishable, especially ones that are really old. Try to provide a reason even if it’s hand-wavey. “Feel free to reopen”.

I feel this has some risks for our team and possibly also limited rewards, so I don't recommend it.

Gather more info?

We could do this, but I think we have enough info based on this research, people we've already talked to, and our experiences over the past few years (In 2022, the now-defunct Developer Advocacy also researched the topic of onboarding and retaining newcomers).

Appendix

These sections contain work that I completed before I started doubting the validity of my entire project :_-(.

Imaginary criteria for Good First Doc Tasks

FYI: adding the "good first task" tag in Phabricator auto-adds this message, so our tech docs criteria can't contradict this:

"A good first task is a self-contained, non-controversial task with a clear approach. It should be well-described with pointers to help a completely new contributor, for example it should clearly point to the codebase URL and provide clear steps to help a contributor get set up for success. We've included some guidelines at https://phabricator.wikimedia.org/tag/good_first_task/ !" - Herald (Phab bot)

Well-defined and limited scope

• Avoid broad topics or projects that span multiple areas and many documentation pages*. For example, instead of documenting an entire software system, or improving all the docs for a team or product, a good first task focuses on documenting topics like a specific function, module, extension, or pipeline.
• List (with links) all the wiki pages or page sections that are in-scope for the work.
  • Content changes should be limited to one or two sections on a page. Changing the content on an entire page is too large in scope (and causes added complication with translated pages).
• Link to the code repository, or ideally, specific code files, that are specifically relevant for the task.
  • GFTs should not require the assignee to use code search or dig around in code.

*Exception: sometimes a good first task involves simple or repeated changes across many pages, to improve documentation consistency. Even in such cases, the scope of which pages to update should still be defined.

Learning opportunity

This depends on the goal and audience of GFTs. If we're creating them with onboarding newcomers as the main goal, then learning is priority. If we're creating them with enabling impactful doc improvements by anyone as the main goal, learning is lower priority.

For newcomers seeking to learn: GFTs should provide an opportunity to learn and use fundamental skills like writing clearly, organizing information logically, working in the Wikimedia context, and using appropriate tools – but probably not all at the same time. Tasks that involve too many of these skills quickly become too challenging or complex.

Key topics people should learn about before they start: TODO

Procedure (incomplete):

• Make changes like you would make code commits, by breaking down the changes into edits that make it easy to conceptualize each change and adding a detailed edit summary describing the rationale. Limit edits to a few per day to give other editors time to respond. Then, if an edit is reverted, you can post on the talk page to start a conversation about the change and hopefully get consensus.
• If you make changes to a translated page, and plan to make more, add a template like {{DoNotTranslate}}, or make a comment on the Talk page to let Translate admins know the page content is not yet stable. Translation admins can wait to mark a set of changes for translation until the content has reached a stable state, but it can help them if you make your intentions known.

Goal-focused doc improvements

Doc work can address various types of goals. To prevent scope from becoming too large or ambiguous, focus a single task on a single documentation goal.

Idea: goals that correspond to documentation metrics?If we can tie tasks to doc metrics, maybe we can help motivate people and show that outreach efforts can have a measurable impact (improvement by a thousand papercuts, and very much dreaming)?

MDN's issue tracker has some evidence of them trying this, but the categories are labeled as experimental and don't appear to be heavily used.

Clear and concise task instructions

Just like technical documentation, a good first task should follow writing best practices for readability and structure, so that people can quickly and easily assess whether the task aligns with their capabilities and interests. Task templates help with this…but we need to strike a balance between a template that helps newcomers be successful and work independently, and a template that is so detailed that the task-filer could just do the doc work in the time it takes to file the task.

Before you file a task:

• Search existing tasks to avoid filing duplicates.
• If docs are part of an owned project, check if that project welcomes contributions.

Task template for Good First Doc Tasks

Existing task template: TODO

Ideas for revised task template:

• Who is the target audience of the task?
• What is the task? See the next section below for how to describe a doc task.
• What knowledge and skills are required?
  • Edit wikis (wikitext)
  • Edit markdown and send PRs using Gerrit/GitLab
  • Write in English, following the Style Guide
  • Work with translated pages (Translation markup)
  • Write and edit code using git workflows, with ability to send PRs using Gerrit/GitLab.
  • Ability to install and run code locally
  • Familiarity with MediaWiki codebase
  • Familiarity with the command line and shell scripts
  • Ability to write and test simple API queries
  • Ability to write and test simple SQL queries
  • Domain- or topic-specific knowledge:
    • [Fill in the blanks]
  • What is the definition of "Done" (the acceptance criteria) for this task?
• Where can the assignee find information necessary to help them complete the task?
  • Link to relevant code
• Where can the assignee ask for help?
• Who is available to review the work?

How to describe a doc task

Include an appropriate amount of detail: just enough, and not too much.

• Include: Historical / technical decisions that directly impact the docs covered by the task. TODO example
• Exclude: history of the tech stack, why things are the way they are, varying opinions about architecture decisions or directions, examples of how other places do it, etc. TODO example
• Include: Links to key terms and background context necessary to orient people to the space. If docs use jargon or special terms, provide links or update docs to explain what they are.
• Exclude: Lengthy explanations and long lists of links. Don't expect or ask people to become an expert in order to do a basic doc task. Focus on providing the minimum viable information necessary.

Criteria considered but rejected

Should good first tasks be limited to docs that are part of owned projects? Many docs are not part of owned projects - many docs span projects, or the projects are unowned. Ownership would help ensure a SME is available for questions, even if not as a task mentor?)

• Decision: No, because this is hard to identify when filing a task, and it changes over time, which would make it difficult to keep tasks updated.
• TODO: How do we avoid people putting effort into tasks that are no longer relevant? We would need to constantly monitor the Phab tag and make our own assessments about content and ownership if the tag is added to mysterious issues about random docs. Maybe this wouldn't happen very often, so it's fine?

Working with translated content is really hard. Should we recommend that translated pages be excluded from what qualifies as a GFT?

• Decision:No, because this would eliminate many pages, including some of the most important and frequently-visited. Also, if the task is appropriately scoped, it should involve a minimal exposure to Translate markup, at a level that is tolerable with a basic introduction to how to work with translated pages.