Documentation/Audiences for Wikimedia technical documentation

Who's using your technical documentation?

Audience profiles, user personas, developer stories, user stories, user journeys, 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

How to use audience profiles

Not all documents will work for all users. When you are working on technical documentation, audience profiles can help you envision the people who will be reading your documentation. You can use the profiles below to build sets of audiences and their motivations. This can help guide the purpose of your documentation and create requirements. Are you meeting the needs of your audiences?

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.

Audiences

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 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 or a movement affiliate.
• I am new to open source.

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 am looking for co-maintainers for a tool I am building.
• 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 want to share information about the work my team is doing.
• I am interested in what the Wikimedia technical community is doing.
• I am interested in learning about tools and services that will make it easier for me to contribute to Wikimedia technical projects.
• I am new to open source and have heard that Wikimedia technical projects are a good place for developers to start.
• 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 am looking for opportunities to contribute to open source to build my development skills or to gain experience for employment.
• I am interested in what the Wikimedia technical community is doing.
• I want to participate in hackathons and other events related to the Wikimedia technical community.
• I want to contribute to Wikimedia technical documentation.

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 or movement affiliate 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 re-users 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.

Data consumers

Data consumers 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.

Designers

Experience level

• I am a designer at the Wikimedia Foundation or a movement affiliate.
• I am an experienced designer who volunteers on Wikimedia projects.
• I am not an experienced designer, but I'm interested in how Wikimedia sites and apps are designed.

User stories

• I am interested in the design of Wikimedia sites and apps/products.
• I am interested in improving the accessibility of Wikimedia sites and apps/products.
• I am 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.
• I am interested in what the Wikimedia technical community is doing.
• I want to contribute to documentation about design.

Translators

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.
• I want to contribute to documentation about translation.
• I am interested in what the Wikimedia technical community is doing.

Technical Writers

Experience level

• I am an experienced technical writer.
• I am a developer without a lot of writing experience.
• I am a writer without a lot of development 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 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 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 am interested in what the Wikimedia technical community is doing.
• I want to know more about how to become a better technical writer.
• I am interested in automating technical documentation.
• I want to apply to participate in an outreach program through Wikimedia.
• 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 technical writing portfolio, 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
• Digital 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.