Documentation/Tools/Documentation metrics dashboard/Requirements

This page contains the original requirements and non-requirements for the documentation metrics dashboard. For information about the development status, see task T334839 and task T356976.

Functional requirements (MVP)

Listing page pile contents

As a user

I want to specify a page pile ID and view the pile's contents before opening the dashboard

So that I can ensure I'm requesting the dashboard for the correct list

Given that I am a user on the application's landing page 
When I provide a valid page pile ID with pages from tech wiki, meta wiki, or mediawiki.org 
And I click Load
Then I will see the list of pages from that page pile

Given that I am a user on the application's landing page 
When I provide an ID of a page pile that doesn't exist 
And I click Load 
Then I will see an error message that explains this page pile doesn't exist

Given that I am a user on the application's landing page 
When I provide an ID of a page pile that exists but contains pages from a wiki other than tech wiki, mediawiki, or meta wiki
And I click Load 
Then I will see an error message that explains this page pile is unsupported

Page pile history

As a user

I want to see a list of page piles I accessed previously

So that I can quickly find information about collections interesting to me

Given that I have explicitly set the Remember my page piles setting 
And I have consented to the application's usage of cookies and local storage 
When I successfully load content of a valid page pile 
Then this page pile is added to my page pile history

Given that I am a user who previously used the application in the same browser 
And I have explicitly set the Remember my page piles setting and consented to the applications' usage of cookies and local storage 
When I open the metrics dashboard 
Then I will see the list of collections I opened previously

Opening the dashboard

As a user

I want to access the statistics dashboard for pages in the page pile I requested

So that I can view the relevant page statistics

Given that I have loaded pages from a valid page pile 
And I am seeing the list of pages from that page pile 
When I click Open page pile statistics 
Then I will see the dashboard for that page pile

Dashboard - default view

As a user

I want to see aggregated information about an entire page pile based on information about individual pages

So that I can make high-level decisions about work needed to improve specific collections

Given that I am a user with the dashboard for a page pile open 
When I scroll down the page 
Then I will see different representations of aggregated documentation metrics

As a user

I want to see a list of pages in a page pile

So that I can view the statistics for a single page instead of the entire page pile

Given that I am a user with the dashboard for a page pile open 
When I click a specific page in that page pile 
Then I will instead see the statistics for that page only

As a user

I want to sort pages listed on the dashboard based on statistics

So that I can find pages where my contributions could have the highest impact

Dashboard - page view

As a user

I want to see the statistics for a single page instead of the entire page pile

So that I can understand which pages require documentation work

Dashboard - available metrics

As a user

I want to have access the following information on the dashboard:

• Number of page views, breakdown by day - in graphical or numerical form
• Number of page edits, breakdown by day - in graphical or numerical form
• Number of major edits vs minor edits - in graphical or numerical form, number of small (<1000b) and big (>=1000b) edits
• List of most active contributors with their statistics
• List and number of Phabricator tasks that mention the page
• General page information, page categories, incoming and outgoing links (only for individual pages), numbers of incoming and outgoing links (aggregated for the entire page pile), information about whether the page is marked for translation (and the percentage of pages in a page pile that are marked for translation).
• Indication whether a page uses specific templates, such as "Draft", "DoNotTranslate", "Outdated", or "Historical".

So that I can reason about the quality of pages and collections

Cookies or local storage usage

As a user

I want to see a blocking cookie or local storage popup or modal window when I attempt to use any application feature that uses cookies or local storage

So that I can grant the application my explicit consent to store data on my device

Functional requirements (later)

This sections describes functional requirements that we plan to meet in a later version of the dashboard.

Support for GULP

As a user

I want to provide a GULP list number

So that I can see the statistics dashboard for the collection represented by that list

Support for manually constructed lists and doc.wikimedia.org

As a user

I want to manually specify a list of valid pages from doc.wikimedia.org, tech wiki, mediawiki.org, and meta wiki to include in a collection

So that I can see statistics for more complicated page lists

This feature will allow us to construct lists with valid pages from multiple wikis and doc.wikimedia.org. PagePile only support lists with pages from a single wiki.

Note that some statistics might not be available for doc.wikimedia.org pages. We need to consider and implement this carefully so that we don't undermine the accuracy of our data.

Sharing custom lists

(depends on Support for manually constructed lists)

As a user

I want to share my custom list using a simple code or number

So that I can help other users gain insight about lists of pages I have already built

Custom collections as a tree or table of contents

(depends on Support for manually constructed lists)

As a user

I want to see the hierarchy of pages within a collection created directly in the application represented as a tree instead of a list

So that I and others can reason about the information architecture of the collection

Flat lists have limited use for technical writers. Trees are better at representing hierarchies of information. While this will not impact the statistics, having access to hierarchies of information in the form of trees will definitely help us reason about collections.

Linter integration

As a user

I want to have access to linter output for a specific page on the dashboard

So that I can see content change recommendations based on commonly used style guides

To implement this using vale.sh, we would need to create and maintain support for wikitext syntax ourselves (see https://vale.sh/docs/topics/scoping/#formats), or come up with a workaround.

Export to JSON

As a user

I want to be able to export dashboard information to a well-structured JSON file

So that I can use and process the data in another tool

Dashboard - additional metrics

As a user

I want to have access to the following additional information on the dashboard:

• Number and percentage of pages that have been translated. Number of translation pages for each page.

So that I can reason about the quality of pages and collections and consider translation impacts in my work

Non-functional requirements

Public access

The application is publicly available on the internet, under a URL that's easy to use and remember.

Personal preferences

The application doesn't require login and supports only one type of user - an anonymous user. Any user preferences and lists history are stored either in a cookie or in local storage (subject to user’s consent).

Localization

The application supports localization and allows users to set their preferred interface language. This setting is stored in their cookies or local storage if they have consented to their usage.

The application supports both LTR and RTL languages.

Inclusive design

The governing design principle is: "The application is easy to see, easy to hear, easy to interact with, and easy to understand".

The application allows users to set their preferred interface font to a dyslexia-friendly typeface.

The application's design follows the principles of neurodiversity design available on https://neurodiversity.design.

The application is designed from ground up to use all the modern accessibility features, with WCAG being the baseline.

The application is designed to minimize the CPU and RAM requirements of a device it is used on.

The application is designed to work well on internet connections with lower bandwidth and worse connection stability.

The application aims to serve users at the 75th percentile of devices and networks.

Caching

The application uses caching to minimize the number of requests to external APIs. Consecutive requests for the same data do not result in consecutive calls to these APIs.

Non-requirements

This section describes what we've decided not to implement.

User login and management

The dashboard does not provide any mechanisms of user management, login, or registration. Any preferences, custom data, and (eventually) manually-created lists are stored locally and are visible only to their creator.

Content moderation

The dashboard requires no moderation as it doesn't allow users to edit any publicly-visible data. Any user-created data is only visible to them.