Core Platform Team/Initiatives/Developer Portal
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on any information on this page. The Core Platform Team and its initiatives do not exist anymore. See MediaWiki Engineering Group instead since 2023. For the 2020–2022 Developer Portal project, visit Developer Portal instead. |
|
Developer Portal
|
Initiative Vision
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on any information on this page. The Core Platform Team and its initiatives do not exist anymore. See MediaWiki Engineering Group instead since 2023. For the 2020–2022 Developer Portal project, visit Developer Portal instead. |
Product Initiative Vision Table
Vision:
| |||
Target Group(s):
|
Needs:
|
Product:
|
Aligned Goals:
|
Initiative Description
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on any information on this page. The Core Platform Team and its initiatives do not exist anymore. See MediaWiki Engineering Group instead since 2023. For the 2020–2022 Developer Portal project, visit Developer Portal instead. |
- Summary
Develop a site that collects documentation relevant to developers into an easy-to-use format
- Significance and Motivation
Developers who want to target our platform have a hard time finding relevant documentation
- Outcomes
Developer portal available for developers
- Baseline Metrics
Documentation is available from multiple sources
- Target Metrics
Lower time for developers to find documentation
- Stakeholders
- Developer Advocacy
- Audiences
- Known Dependencies/Blockers
None given
Epics, User Stories, and Requirements
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on any information on this page. The Core Platform Team and its initiatives do not exist anymore. See MediaWiki Engineering Group instead since 2023. For the 2020–2022 Developer Portal project, visit Developer Portal instead. |
Objectives
- Extend the reach of Wikimedia content by making it easy for developers to include Wikimedia content in their apps and platforms.
- Connect developers with the Wikimedia API or tool best suited to their use case. Find a balance between overwhelming them with choices and obscuring the underlying tech to the extent that it impedes their ability to get support.
- Uphold Wikimedia principles by keeping things open, reducing friction for participation, and fostering a community of contributors.
- Avoid excessive manual duplication of content.
- Use MediaWiki as the CMS.
Epic 1: Prototype
The goal of this epic is to have a prototype of the developer portal that stakeholders can review to understand how the developer portal will work. The design and content strategy is largely based on the user stories in Epic 2.
Personas in this epic:
- Developer: developer of the future Developer Portal
- Tech Writer: a tech writer for the future Developer Portal
- Designer: a designer for the future Developer Portal
- Stakeholder: anyone interested in seeing the Developer Portal be a success.
| ID | User Story | Priority | Notes |
|---|---|---|---|
| 1 | As a Designer, I want to see the proposed Web interface design, so that I can implement it in the future epics. | Must Have | This is a design, not a finished skin. |
| 2 | As a Tech Writer, I want to see the subject areas that will be covered in the Developer Portal, so that I can prepare content for it. | Must Have | Represented with documentation and prototype content |
| 3 | As a Tech Writer, I want to see the content types that will be covered in the Developer Portal, so that I can structure the content correctly. | Must Have | Represented with documentation and prototype content |
| 4 | As a Developer, I want to see the proposed Web navigation, so that I can implement it in the future epics. | Must Have | Documentation and non-working prototype navigation |
| 5 | As a Stakeholder, I want a clickable prototype with sample content, so I can evaluate the design of the Developer Portal directly. | Must Have | Clickable prototype |
Epic 2: MVP
In this epic, an initial capability will be provided with the ability to manage developer client keys and some initial developer documentation.
Design decisions:
- use Chameleon as the skin for the dev portal
- it would be configured to look similar to the prototype, but certain items such as the behaviors/flyouts would not be exactly as they would look like Bootstrap
- coordinate with Stephan Gambke so he is aware in case we need to submit any pull requests to Chameleon
- do not make any changes to the UI of the special pages in the OAuth extension as part of this project
- we had initially thought that would be necessary, but it would distract from the work that is necessary for the dev portal
- create a new extension that provides a simple UI to create simple OAuth 2 consumers as shown in the prototype
- the new extension will only be installed on the dev portal
- the new extension will interact with the OAuth extension installed on meta through an API
- the new extension will be named WikimediaDevPortal and could also contain other UI elements needed for the dev portal
- there would be an attempt to limit any additional libraries necessary for the UI
The personas in this epic are:
- developer who wants to use the MediaWiki Core REST API
| ID | User Story | Priority | Notes |
|---|---|---|---|
| 1 | As a developer, I want to create a new client | Must Have | |
| 2 | As a developer, I want to list all my clients | Must Have | |
| 3 | As a developer, I want to delete one of my clients | Must Have | Although from the user perspective, the client will be deleted, it will actually only be permanently disabled, since clients must be retained for logging purposes. This may be relaxed if the client is deleted before it is approved. |
| 4 | As a developer, I want to create an access token for my account with one of my clients (“developer token”) | Optional | The back-end functionality to create access tokens may not be available before the MVP is complete. |
| 5 | As a developer, I want to delete an access token for my account with one of my clients | Optional | |
| 6 | As a developer, I want to show access tokens for my account with one of my clients | Optional | |
| 7 | As a developer, I want to read documentation on the core REST API | Must Have |
Epic 3: Publication
In this epic, our deliverable is an initial published version of the documentation chosen in Epic 1, in the formats chosen in Epic 1.
The personas in this epic are:
- Application developer: I want to include Wikimedia content (Wikipedia articles, Wikivoyage travel listings, Wikidata data items) into my application.
- A software developer for a mobile or Web application
- They may work for a small (<100 person) company
- They are experienced with other APIs, like the Twitter or Twilio API
- They are judgemental about APIs and technologies that seem old or uncool
- Using Wikimedia content is an optional feature for their application; they will abandon the process if the barrier to entry is too high
- They may not use English as their primary language, but they are used to English-only developer documentation.
- Example: “Mid-level Mobile developer at a small application development agency needs to use Wikivoyage data in a bespoke travel app she is developing for a client.”
- Community script or gadget developer: I want to implement important features for Wikimedia sites that aren’t enabled in the core software, such as updating all imperial measurements (pounds and feet) with additional metric measurements (kg and meters).
- Either an amateur software developer, professional working off hours, or power user with some scripting experience.
- They are very involved in one or more Wikimedia projects
- They are frustrated with manual processes that are repetitive or complex
- They do not have a choice about using Wikimedia APIs; there are not any other options.
- They may not have experience with other APIs.
- They have experience with using MediaWiki for documentation and for conversations.
- They may not use English as their first language.
- They may “program by example”, copying example code and adapting it to their own needs.
- They are passionate about cleaning up vandalism.
- Example: “Tech librarian for a medium-sized liberal-arts college who is organizing a Wikipedia edit-a-thon for their school and wants to find topics related to their university or area that don’t yet have articles or are not well covered.”
- Professional platform developer: I want to syndicate Wikimedia content (mostly Wikipedia articles in English, sometimes Wikipedia articles in other languages, and sometimes Wikidata data items) to my own platform
- A professional software developer working for a large (>10,000 person) company.
- They may be part of a team (10-50 person).
- Platform may be text (Google Knowledge Graph or Facebook OpenGraph) or voice (Siri, Alexa, Cortana, Google Assistant)
- They either use English as their first language or they are used to English-only developer documentation.
- They think of Wikimedia sites as “dirty” data sources that need to be “cleaned up”. They expect to add a lot of value to the data available from Wikimedia sites.
- Example: “Knowledge engineer at Banana Computing who works on the Sara voice assistant platform. They are responsible for answering sports data questions, like who won a particular baseball game in 1972.”
| ID | User Story | Priority | Notes |
|---|---|---|---|
| 1 | As an app developer, I want to read simple how-to guides for including Wikimedia content into apps on my platform (iOS, Android, Web), so I can more easily implement the code, and understand what I will need to do, how complex this process will be and how long it will take me to do it. | Must Have | |
| 2 | As an app developer, I want to know any license requirements, terms of service, rate limits, authentication, or other restrictions on my use of the APIs, so that I can properly determine if this API meets the needs of my project before I start implementing the code. | Must Have | |
| 3 | As a Community script developer, I want to read simple HOWTOs for executing common tasks like replacing text in Wikipedia articles, so I can more easily implement the code, better understanding what I will need to do, how complex it is and how long it will take me to do it. | Must Have | |
| 4 | As a Community script developer, I want to quickly find the right API call to do what I need, so I don't waste time searching for the right API better spend my time digging into the details. | Must Have | |
| 5 | As a Community script developer, I want to download example code that I can adapt quickly for my needs, because based on my personal process, I code quicker when pasting example code and editing versus coding from scratch. | Must Have | |
| 6 | As an app developer, I want to read detailed API references, including input formats and values, output formats and values, and possible side-effects, so I can get exactly the right behaviour I want. | Must Have | |
| 7 | As an app developer, I want to experiment with API calls, either with a “curl” recipe, or with an in-page API client, to make sure I understand the documentation. | Must Have | |
| 8 | As an app developer, I want to know about any official or unofficial libraries for my preferred programming language (Ruby, Python, Go, etc.) and/or platform (iOS, Android, Windows). | Must Have | |
| 9 | As a Community script developer, I want to read detailed API references for obscure API calls that may not be covered by tutorials or HOWTOs, so I can implement obscure functionality that most developers don’t use. | Must Have | |
| 10 | As an app developer, I want to ask a question that isn’t covered in a tutorial or API reference, so that a developer evangelist or an experienced developer who's used this API before can answer my question. | Must Have | |
| 11 | As a Professional platform developer, I want to know about bulk data transfers to get the most data in the most efficient way. | Must Have | |
| 12 | As a Professional platform developer, I want to have detailed performance information for API calls, to best understand how this API will impact the performance of my project. | Must Have |
Epic 4: Editorial
In this epic, we'll iterate on the initial content of the Developer Portal, and improve the publication processes.
Personas in this epic:
- Tech Writer: a tech writer developing content for the Developer Portal
- Technical Editor: an editor who manages the work of one or more tech writers
- Developer Advocate: a developer advocate trying to get more people to use our platform
- API Developer: a developer creating APIs for the Wikimedia platform
- Reader: a person reading text on the Developer Portal
| ID | User Story | Priority | Notes |
|---|---|---|---|
| 1 | As a Tech Writer, I want to publish content once, and share it to different platforms automatically. | Optional | For publishing to mediawiki.org and the Developer Portal simultaneously, e.g. |
| 2 | As a Technical Editor, I want review technical documentation before it's visible to the public, so I can ensure high quality and factual accuracy. | Optional | Adding an editorial step |
| 3 | As an API developer, I want changes I make to API definitions in my code to be updated automatically on the Developer Portal, so that it's always up-to-date with the latest interfaces in production. | Optional | Saving some steps in API references |
| 4 | As a Developer Advocate, I want to publish new example code and case studies, to feature interesting application areas for developers. | Optional | Publishing fresh content, perhaps in blog form |
| 5 | As a Developer Advocate, I want to answer questions posted by developers on the Developer Portal, so that they can be successful using our platform. | Must Have | Adding answers; maybe also a FAQ? |
| 6 | As a Reader, I want to correct errors or confusing language in the documentation, so that others can benefit from my learning. | Optional | Compare MDN |
Subpages