Documentation/Audiences for Wikimedia technical documentation

Who's using your technical documentation?
Audience profiles, user personas, developer stories, user stories, user journies, etc. can be very useful tools when you want to picture the people who are using your technical documentation.

This page contains a list of audience profiles for Wikimedia technical documentation. The goal is to provide details about the types of people who visit our sites looking for technical information that will enable them to understand and support our projects. Each person has a different journey. Audience profiles give us insight into that journey. What are the motivations, needs, and frustrations of the people coming to Wikimedia sites in search of technical information? What needs and requirements do different audiences share in common?

We can use these profiles to inform the creation of specific documentation for target audiences and to guide decisions about how to prioritize, craft, and organize technical documentation that better serves the needs of multiple audiences.

Universal experience
Different people arrive at Wikimedia sites by different methods and with different motivations and different goals. While their experiences and needs may be different, they share some common expectations.

Each person who comes looking for documentation and information should find it easy to:


 * Know where to begin
 * Understand what resources are available to them
 * Find what they need to complete their task
 * Read and follow the documentation
 * Understand how to make contributions of their own

Better practices
The audience profiles and user stories listed here are not exhaustive; they do not cover every possible user or scenario. Creating and organizing technical documentation for a large, diverse group of users is a monumental task, and while it's an admirable goal to try to serve everyone, it may not always be possible to meet everyone where they are at. Describing specific audiences and identifying where their wants and needs intersect is an exercise that can help guide us in the curation of quality documentation for a greater number of users.

Whenever possible, strive to follow consistent practices when creating and organizing technical documentation to create a better experience for everyone who interacts with technical documentation on Wikimedia technical projects regardless of which audience or audiences they belong to.

For example:


 * Follow an agreed-upon style-guide
 * Follow community guidelines
 * Provide real, clear examples

Criticisms
The quality and usefulness of the audience profiles described here are limited by the knowledge and experiences of the people who create them. Some audiences may be obvious; others may not. If you are aware of additional audiences and stories not listed here, please share your thoughts on the talk page for further discussion.

Don't assume the information here will tell you everything you need to know about a given audience. Make sure to test your assumptions (and your technical documentation) with real people.

Considerations
This section needs additional work
 * Accessibility
 * Translation
 * Inclusion

Audiences
This section needs a lot of work!

MediaWiki users
End-users of sites that use MediaWiki— not necessarily Wikimedia projects.

Experience level

 * May have no prior familiarity working with wikis.
 * I may not have any or limited coding skills.

User stories

 * I want to understand what a wiki is and how it is used.
 * I want to understand how to use MediaWiki software.
 * I want to run my own wiki using MediaWiki or find someone who can help me with this.
 * I want to customize my wiki experience in my browser or find someone who can help me with this.
 * I want to understand how and where to host a wiki or find someone who can help me with this.
 * I want to see examples of different wikis.
 * I am not interested in what the Wikimedia community is up to.
 * I am not interested in contributing to Wikimedia or MediaWiki documentation.

Professional MediaWiki developers and consultants
Focused on MediaWiki software, not necessarily for Wikimedia projects.

Experience level

 * I am an experienced developer and/or consultant; MediaWiki is my job.
 * I am a member of MediaWiki Stakeholders group.
 * I am a PHP developer.

User stories

 * I want to develop new functionality and extensions for MediaWiki.
 * I want to provide training on MediaWiki for my clients.
 * I want to help others install, upgrade, and customize MediaWiki.
 * My organization hosts MediaWiki installations.
 * I want to report problems with MediaWiki software.
 * Beyond MediaWiki, I may not be interested in what the Wikimedia community is up to.
 * I want to contribute documentation related to MediaWiki software.

Wikimedia developers
Focused on developing tools, bots, and scripts and improving the software that supports Wikimedia projects. These audience profiles will overlap with the "Newcomers'" profiles. The experience levels and user stories listed here are broadly defined. This page provides more in-depth information about specific Wikimedia developer audiences.

Experience level

 * I am an experienced developer.
 * I have some programming experience.
 * I am technically curious, but I have little or no programming experience.
 * I am a developer on a team at the Wikimedia Foundation.

User stories

 * I want to make a technical contribution to a Wikimedia open source project.
 * I want to complete a specific task related to Wikimedia technology.
 * I want to understand a specific concept related to Wikimedia technology.
 * I want to automate maintenance tasks for a Wikimedia project.
 * I want to build or improve the software that supports a Wikimedia project.
 * I want to help make it easier for others to contribute to Wikimedia projects.
 * I need help troubleshooting a specific technical issue.
 * I want to report a problem or reach out with questions about something I am working on.
 * I want to connect with other developers who are working on Wikimedia projects.
 * I'm looking for co-maintainers for a tool I am building.
 * I want to share information about the work my team is doing.
 * I’m interested in what the Wikimedia technical community is doing.
 * I want to contribute documentation to a Wikimedia project.
 * I am interested in learning about tools and services that will make it easier for me to contribute to Wikimedia technical projects.
 * I want to participate in Wikimedia mentorship programs.

MediaWiki administrators
Administrators are users with the technical capability to protect and delete pages, block users, and edit protected pages, among other things. They may or may not be working on Wikimedia projects.

Experience level

 * I am an experienced software developer.
 * I am a Wikimedia Foundation staff member or volunteer

User stories

 * I want to perform or automate maintenance tasks for a MediaWiki site.
 * I want to perform or automate maintenance tasks for a Wikimedia project.
 * I want to grant specific permissions to individuals interacting with a wiki.
 * I want to contribute documentation to a Wikimedia project.

Business class users
Large-scale for-profit reusers of Wikimedia content.

Experience level

 * I am an experienced developer
 * I may or may not have prior familiarity with Wikimedia projects

User stories

 * I want to use Wikimedia Enterprise to reuse Wikimedia content at a large scale.

Researchers
In this context, "researcher" refers to someone trying to find an answer to a question, and not necessarily to someone with a particular academic background or level of coding skill. Researchers use the dumps and wiki replicas via Toolforge, Quarry, and PAWS (and Cloud VPS in some more sophisticated cases) to write/run scripts and database queries to figure something out about the Wikimedia projects.

Experience level

 * I am an academic researcher.
 * I am on the Wikimedia Research Team.
 * I am a student or outreach program participant (Outreachy, Google Summer of Code, Google Season of Docs, etc) who needs to use Wikimedia data as part of a learning project or internship.
 * I have experience using programming languages related to data science (Python, R, Julia, C/C++, Java, Scala, JavaScript, etc).
 * I have little or no experience using programming languages related to data science (Python, R, Julia, C/C++, Java, Scala, JavaScript, etc).

User Stories

 * I want to contribute documentation to a Wikimedia project.
 * I want to use Wikimedia data in my research or data analysis.
 * I want to use Wikimedia data to answer a question.
 * I want to complete a specific task related to Wikimedia data.
 * I want to understand the kinds of data that is available to me and how to access it.
 * I want to know what tools Wikimedia technology offers to help me work with data and how to use them.
 * I want to understand what the Wikimedia Research team does.
 * I want to collaborate with the Wikimedia Research Team.
 * I want to develop tools and contribute to improving software that is related specifically to working with Wikimedia data.
 * I want to contribute to documentation about Wikimedia data.
 * I am interested in what the Wikimedia technical community is up to.

Experience level

 * I'm part of the Design Team at the Wikimedia Foundation.
 * I'm an experienced designer who volunteers on Wikimedia projects.
 * I'm not an experienced designer, but I'm interested in how Wikimedia sites and apps are designed.

User stories

 * I'm interested in the design of Wikimedia sites and apps/products.
 * I'm interested in improving the accessibility of Wikimedia sites and apps/products.
 * I'm interested in how design decisions are made.
 * I want to learn about design standards for Wikimedia sites and apps/products.
 * I want to improve the design of something I or someone else has developed.
 * I want to learn how to use specific design tools.

Translators (and people working with translated pages)
Anyone who is translating content on Wikimedia projects from one language to another, and individuals who are editing pages that have been marked for translation.

Experience level

 * I am new to content translation.
 * I am an experienced translator.
 * I am a translation administrator.
 * I am an editor or contributor working with pages that have been translated.
 * I am trying to build my skills as a content translator.

User stories

 * I want to mark pages for translation.
 * I want to translate a wiki page into another language.
 * I want to know which wiki pages are prioritized for translation.
 * I want to understand how to use translation templates.
 * I want to edit a page that is already marked up with translation templates.

Experience level

 * I am an experienced technical writer
 * I am a developer without a lot of writing experience
 * I am a new contributor to Wikimedia technology projects
 * I am a student or outreach program participant (Outreachy, Google Summer of Code, Google Season of Docs, etc) who needs to use Wikimedia data as part of a learning project or internship.

User stories

 * I want to write create technical documentation for a project I or someone else is working on.
 * I am looking for a style guide and/templates to help me get started with technical documentation.
 * I want to improve some bad documentation I discovered or report it to someone who can fix it.
 * I want to contribute to Wikimedia technology, but I don't know how to code or don't want to contribute build tools or software.
 * I want to know more about how to become a better technical writer.
 * I'm interested in automating technical documentation.

Newcomers
Typically refers to individuals who are new to the Wikimedia technical community.

Note: "Newcomer" may not be the right word to capture this audience profile. It can become a catch-all for a large group of people who don't fit under the other audience profiles. There could be a large overlap with "Wikimedia Developers."

Experience levels

 * I am an experienced software developer.
 * I have some software development skills.
 * I am interested in software development but have little or no experience.
 * I am a researcher (someone trying to find an answer to a question using Wikimedia data; may not be academic or have coding skills).
 * I am a student or outreach program participant (Outreachy, Google Summer of Code, Google Season of Docs, etc) who needs to use Wikimedia data as part of a learning project or internship.
 * I am new to the open source community.

User stories

 * I am interested in what the Wikimedia technical community is doing.
 * I want to understand how to complete a specific task related to Wikimedia technical projects.
 * I want to understand a specific concept related to Wikimedia technical projects, MediaWiki software, or open source software, in general.
 * I am interested in working with data and have heard that Wikimedia projects are a good place to start.
 * I am new to open source and have heard that Wikimedia technical projects are a good place for new contributors to start.
 * I am looking for a mentor or peers who can support me when I have questions about Wikimedia-related tasks I am working on.
 * I have an idea for a tool, bot, script that will help improve the wiki I am working on and need to connect with an experienced developer who can help me build it.
 * I want to apply to participate in an outreach program through Wikimedia.
 * I want to learn about coding concepts and/or improve my skills as a software developer.
 * I want to participate in hackathons and other events related to the Wikimedia technical community.
 * I am looking for opportunities to contribute to open source to build my development skills or to gain experience for employment.
 * I want to contribute to technical documentation.

Other possible audiences to explore

 * Students (at a variety of levels)
 * System administrators
 * Wikidata stakeholders
 * Open source community members (curious about Wikimedia projects)
 * Interns and mentees working on projects through Outreach programs (not necessarily newcomers to Wikimedia projects)
 * WMF program/product managers
 * Digitial and academic librarians
 * Tool developers/tool users

Seeking feedback
If you have comments or suggestions for expanding or refining the audience profiles here, please leave a message on the discussion page.