Skip to content

Commit

Permalink
adding doc priorities explainer (#2937)
Browse files Browse the repository at this point in the history 
* adding doc priorities explainer

* updates based on wbamberg feedback

* add numbers of documents in each tree/tier

* alphabetize all the things
  • Loading branch information
@chrisdavidmills
chrisdavidmills authored Mar 10, 2021
1 parent 82c0cc5 commit 7672c76
Show file tree
Hide file tree
Showing 2 changed files with 231 additions and 0 deletions.
224 changes: 224 additions & 0 deletions files/en-us/mdn/contribute/documentation_priorities/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,224 @@
---
title: MDN documentation priority list
slug: MDN/Contribute/Documentation_priorities
tags:
- Best practices
- Community
- MDN
- Documentation
- Priorities
---
<p>{{MDNSidebar}}</p>

<p>This document defines the different priority tiers on MDN, and states what documentation topics exist inside each tier — we are calling them <strong>Tier 1</strong> and <strong>Tier 2</strong>.</p>

<p>The purpose of this document is two-fold:</p>

<ul>
<li>To help apply priority measures to content bugs during our triage process, which in turn helps contributors to make a decision about what bugs to work on by finding out which ones are most important right now.</li>
<li>To help contributors that want to work on a specific topic area rather than a specific bug decide which one would be most useful to give their time to (for example, folks that like to run automated cleanup scripts on MDN).</li>
</ul>

<p>The relative importance of these docs has been decided purely by looking at page view figures. There are lots of measures we could have used, but page views is objective and still a good indicator — more important web technologies are looked up more often, and therefore fixing problems with those docs seems most critical.</p>

<p>Also bear in mind that these Tiers are made up of isolated document trees (i.e. the linked page, plus all of the documents in the hierarchy below it). Sometimes a Tier 1 document will link to a Tier 2 document, or vice versa, and that is OK.</p>

<p>The numbers in parentheses after each document tree represent the number of documents under that tree. These numbers will likely change over time, so may need revisiting before too long.</p>

<h2 id="tier_1">Tier 1</h2>

<p>Tier 1 content is the most important content on MDN — it has the most users, and is deemed to cover the most important technologies for the web platform.</p>

<ul>
<li><a href="/en-US/docs/Web/Accessibility">Accessibility</a> (104)</li>
<li><a href="/en-US/docs/Web/CSS">CSS</a> (933)</li>
<li><a href="/en-US/docs/Web/Events">Events</a> (4)</li>
<li><a href="/en-US/docs/Web/HTML">HTML</a> (239)</li>
<li><a href="/en-US/docs/Web/HTTP">HTTP</a> (292)</li>
<li><a href="/en-US/docs/Web/JavaScript">JavaScript</a> (921)</li>
<li><a href="/en-US/docs/Learn">Learn web development</a> (355)</li>
<li><a href="/en-US/docs/Web/Media">Media</a> (17)</li>
<li><a href="/en-US/docs/Web/Performance">Performance</a> (16)</li>
<li><a href="/en-US/docs/Web/Privacy">Privacy</a> (1)</li>
<li><a href="/en-US/docs/Web/Progressive_web_apps">Progressive web apps</a> (16)</li>
<li><a href="/en-US/docs/Web/Security">Security</a> (27)</li>
<li><a href="/en-US/docs/Web/API">Web APIs</a>: The interfaces in the following groups are Tier 1 (see the <a href="#tier_1_webapis">Tier 1 WebAPIs</a> section below for a further breakdown of what this includes (1189):
<ul>
<li>Canvas API (112)</li>
<li>Clipboard API (13)</li>
<li>DOM (439)</li>
<li>DOM Events (22)</li>
<li>Fetch API (47)</li>
<li>File API (48)</li>
<li>HTML DOM (371)</li>
<li>URL API (43)</li>
<li>Web Storage API (8)</li>
<li>WebSockets API (28)</li>
<li>XMLHttpRequest (58)</li>
</ul>
</li>
<li><a href="/en-US/docs/Web/Manifest">Web App Manifests</a> (19)</li>
<li><a href="/en-US/docs/WebAssembly">WebAssembly</a> (12)</li>
<li><a href="/en-US/docs/Web/Web_Components">Web components</a> (5)</li>
</ul>

<p><strong>Total Tier 1 pages: 4150</strong></p>

<h2 id="tier_2">Tier 2</h2>

<p>Tier 2 content is less commonly-used, but useful nonetheless.</p>

<ul>
<li><a href="/en-US/docs/Web/Houdini">CSS Houdini</a> (1)</li>
<li><a href="/en-US/docs/Games">Game development docs</a> (73)</li>
<li><a href="/en-US/docs/Web/Guide">Guides</a> (56)</li>
<li><a href="/en-US/docs/Web/MathML">MathML</a> (38)</li>
<li><a href="/en-US/docs/MDN">MDN meta-documentation</a> (82). This is important, but fixes would be mainly dealt with by the MDN core team)</li>
<li><a href="/en-US/docs/Web/SVG">SVG</a> (382)</li>
<li><a href="/en-US/docs/Glossary">The MDN Web Docs glossary</a> (534)</li>
<li><a href="/en-US/docs/Web/API">WebAPIs</a> that aren't in the "Tier 1 WebAPIs" list (4701)</li>
<li><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions">WebExtensions</a> (635). Not really web platform, but still important)</li>
</ul>

<p><strong>Total Tier 2 pages: 6502</strong></p>

<h2 id="other_content">Other content</h2>

<p>There is other content on MDN that is outside our web platform technology remit — such as archived content and Firefox-specific docs (e.g. DevTools, platform internals). This content has been deprioritised completely, and in most cases we are trying to find new homes for it, or delete it if it is no longer useful. We would not recommend that our community spends any time working on any areas not specifically listed on this page.</p>

<h2 id="tier_1_webapis">Tier 1 WebAPIs</h2>

<p>The following API interface reference documents (and their child pages) are currently considered Tier 1. For more information on the rationale for these groupings and priorities, see the work done in <a href="https://github.com/mdn/sprints/issues/3327">https://github.com/mdn/sprints/issues/3327</a>.</p>

<h3 id="canvas_api">Canvas API (112)</h3>

<ul>
<li><code><a href="/en-US/docs/Web/API/CanvasGradient">CanvasGradient</a></code> (2)</li>
<li><code><a href="/en-US/docs/Web/API/CanvasImageSource">CanvasImageSource</a></code> (1)</li>
<li><code><a href="/en-US/docs/Web/API/CanvasPattern">CanvasPattern</a></code> (2)</li>
<li><code><a href="/en-US/docs/Web/API/CanvasRenderingContext2D">CanvasRenderingContext2D</a></code> (71)</li>
<li><code><a href="/en-US/docs/Web/API/ImageBitmap">ImageBitmap</a></code> (4)</li>
<li><code><a href="/en-US/docs/Web/API/ImageBitmapRenderingContext">ImageBitmapRenderingContext</a></code> (2)</li>
<li><code><a href="/en-US/docs/Web/API/ImageData">ImageData</a></code> (5)</li>
<li><code><a href="/en-US/docs/Web/API/OffscreenCanvas">OffscreenCanvas</a></code> (8)</li>
<li><code><a href="/en-US/docs/Web/API/Path2D">Path2D</a></code> (3)</li>
<li><code><a href="/en-US/docs/Web/API/RenderingContext">RenderingContext</a></code> (1)</li>
<li><code><a href="/en-US/docs/Web/API/TextMetrics">TextMetrics</a></code> (13)</li>
</ul>

<h3 id="clipboard_api">Clipboard API (13)</h3>

<ul>
<li><code><a href="/en-US/docs/Web/API/Clipboard">Clipboard</a></code> (5)</li>
<li><code><a href="/en-US/docs/Web/API/ClipboardEvent">ClipboardEvent</a></code> (3)</li>
<li><code><a href="/en-US/docs/Web/API/ClipboardItem">ClipboardItem</a></code> (5)</li>
</ul>

<h3 id="dom">DOM (439)</h3>

<div class="note notecard">
<h4>Note</h4>
<p>"DOM" is only a partial group — we only included the interface docs with the highest page views, to keep the size of Tier 1 down to a manageable number. Other DOM interfaces not in this list are in Tier 2.</p>
</div>

<ul>
<li><code><a href="/en-US/docs/Web/API/AbortController">AbortController</a></code> (4)</li>
<li><code><a href="/en-US/docs/Web/API/ChildNode">ChildNode</a></code> (5)</li>
<li><code><a href="/en-US/docs/Web/API/CustomEvent">CustomEvent</a></code> (4)</li>
<li><code><a href="/en-US/docs/Web/API/Document">Document</a></code> (164)</li>
<li><code><a href="/en-US/docs/Web/API/DOMParser">DOMParser</a></code> (2)</li>
<li><code><a href="/en-US/docs/Web/API/DOMString">DOMString</a></code> (2)</li>
<li><code><a href="/en-US/docs/Web/API/Element">Element</a></code> (176)</li>
<li><code><a href="/en-US/docs/Web/API/Event">Event</a></code> (24)</li>
<li><code><a href="/en-US/docs/Web/API/EventTarget">EventTarget</a></code> (5)</li>
<li><code><a href="/en-US/docs/Web/API/HTMLCollection">HTMLCollection</a></code> (4)</li>
<li><code><a href="/en-US/docs/Web/API/MutationObserver">MutationObserver</a></code> (5)</li>
<li><code><a href="/en-US/docs/Web/API/Node">Node</a></code> (36)</li>
<li><code><a href="/en-US/docs/Web/API/NodeList">NodeList</a></code> (7)</li>
<li><code><a href="/en-US/docs/Web/API/USVString">USVString</a></code> (1)</li>
</ul>

<h3 id="dom_events">DOM Events (22)</h3>

<div class="note notecard">
<h4>Note</h4>
<p>"DOM Events" is only a partial group — we only included the interface docs with the highest page views, to keep the size of Tier 1 down to a manageable number. Other DOM Events interfaces not in this list are in Tier 2.</p>
</div>

<ul>
<li><code><a href="/en-US/docs/Web/API/EventListener">EventListener</a></code> (2)</li>
<li><code><a href="/en-US/docs/Web/API/KeyboardEvent">KeyboardEvent</a></code> (20)</li>
</ul>

<h3 id="fetch_api">Fetch API (47)</h3>

<ul>
<li><code><a href="/en-US/docs/Web/API/Body">Body</a></code> (8)</li>
<li><code><a href="/en-US/docs/Web/API/Headers">Headers</a></code> (11)</li>
<li><code><a href="/en-US/docs/Web/API/Request">Request</a></code> (15)</li>
<li><code><a href="/en-US/docs/Web/API/Response">Response</a></code> (13)</li>
</ul>

<h3 id="file_api">File API (48)</h3>

<ul>
<li><code><a href="/en-US/docs/Web/API/Blob">Blob</a></code> (8)</li>
<li><code><a href="/en-US/docs/Web/API/File">File</a></code> (15)</li>
<li><code><a href="/en-US/docs/Web/API/FileList">FileList</a></code> (1)</li>
<li><code><a href="/en-US/docs/Web/API/FileReader">FileReader</a></code> (19)</li>
<li><code><a href="/en-US/docs/Web/API/FileReaderSync">FileReaderSync</a></code> (5)</li>
</ul>

<h3 id="html_dom">HTML DOM (371)</h3>

<div class="note notecard">
<h4>Note</h4>
<p>"HTML DOM" is only a partial group — we only included the interface docs with the highest page views, to keep the size of Tier 1 down to a manageable number. Other HTML DOM interfaces not in this list are in Tier 2.</p>
</div>

<ul>
<li><code><a href="/en-US/docs/Web/API/History">History</a></code> (9)</li>
<li><code><a href="/en-US/docs/Web/API/HTMLAudioElement">HTMLAudioElement</a></code> (4)</li>
<li><code><a href="/en-US/docs/Web/API/HTMLCanvasElement">HTMLCanvasElement</a></code> (14)</li>
<li><code><a href="/en-US/docs/Web/API/HTMLElement">HTMLElement</a></code> (45)</li>
<li><code><a href="/en-US/docs/Web/API/HTMLFormElement">HTMLFormElement</a></code> (17)</li>
<li><code><a href="/en-US/docs/Web/API/HTMLInputElement">HTMLInputElement</a></code> (17)</li>
<li><code><a href="/en-US/docs/Web/API/HTMLTextAreaElement">HTMLTextAreaElement</a></code> (2)</li>
<li><code><a href="/en-US/docs/Web/API/Location">Location</a></code> (17)</li>
<li><code><a href="/en-US/docs/Web/API/Navigator">Navigator</a></code> (45)</li>
<li><code><a href="/en-US/docs/Web/API/NavigatorLanguage">NavigatorLanguage</a></code> (3)</li>
<li><code><a href="/en-US/docs/Web/API/NavigatorOnLine">NavigatorOnLine</a></code> (3)</li>
<li><code><a href="/en-US/docs/Web/API/Window">Window</a></code> (182)</li>
<li><code><a href="/en-US/docs/Web/API/WindowEventHandlers">WindowEventHandlers</a></code> (13)</li>
</ul>

<h3 id="url_api">URL API (43)</h3>

<ul>
<li><code><a href="/en-US/docs/Web/API/URL">URL</a></code> (18)</li>
<li><code><a href="/en-US/docs/Web/API/URLSearchParams">URLSearchParams</a></code> (14)</li>
<li><code><a href="/en-US/docs/Web/API/URLUtilsReadOnly">URLUtilsReadOnly</a></code> (11)</li>
</ul>

<h3 id="web_storage_api">Web Storage API (8)</h3>

<ul>
<li><code><a href="/en-US/docs/Web/API/Storage">Storage</a></code> (7)</li>
<li><code><a href="/en-US/docs/Web/API/StorageEvent">StorageEvent</a></code> (1)</li>
</ul>

<h3 id="websockets_api">WebSockets API (28)</h3>

<ul>
<li><code><a href="/en-US/docs/Web/API/CloseEvent">CloseEvent</a></code> (3)</li>
<li><code><a href="/en-US/docs/Web/API/MessageEvent">MessageEvent</a></code> (7)</li>
<li><code><a href="/en-US/docs/Web/API/WebSocket">WebSocket</a></code> (18)</li>
</ul>

<h3 id="xmlhttprequest">XMLHttpRequest (58)</h3>

<ul>
<li><code><a href="/en-US/docs/Web/API/FormData">FormData</a></code> (12)</li>
<li><code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> (40)</li>
<li><code><a href="/en-US/docs/Web/API/XMLHttpRequestEventTarget">XMLHttpRequestEventTarget</a></code> (6)</li>
</ul>
7 changes: 7 additions & 0 deletions files/en-us/mdn/contribute/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,13 @@ <h3 id="Primary_contribution_types">Primary contribution types</h3>

<p>We will add more tasks here as time goes on.</p>

<h4 id="priority_ratings">Priority ratings</h4>

<p>You can also look at priority ratings to give you an idea of what the most important work is to work on — we've started giving content bug issues labels of P0, P1, P2, P3, and P4 to signify how important they are, with lower numbers being more important than higher numbers.</p>

<p>These are figured out during the regular MDN bug triage process, based on the <a href="/en-US/docs/MDN/Contribute/Documentation_priorities">MDN documentation priority list</a>.</p>


<h3 id="Other_task_types">Other task types</h3>

<p>If our main priorities listed above don't interest you, you can find a number of other, more general task types to get involved with below, split up by skillset.</p>
Expand Down

0 comments on commit 7672c76

Please sign in to comment.