User:Pavithraes/Sandbox/Technical documentation prioritization

Overview
The Documentation project on Phabricator is used to track tasks involving technical documentation across Wikimedia spaces.

A set of guidelines have been outlined to help improve the process of categorization and prioritization of these tasks.

Filing a technical documentation request
Requests for improvements, new technical documentation and issues with automated documentation can be filed using Wikimedia's Phabricator instance in the #documentation project.

Ticket Content
A complete and unambiguous description of tasks is the foundation of effective task tracking. Here are a few points to keep in mind while filing a technical documentation request.

For existing docs:


 * Clearly describe the problem. The problem could be wrong information, missing steps, obsolete data, interface changes, etc.
 * Specify the exact location of the problem. You could provide links or point to the exact section that needs work.
 * State the information required to complete/improve the documentation.

For new documentation:


 * Define the purpose of the new document and the topics it should cover.
 * Try to mention a temporary location and title for the documentation.
 * Provide reference resources and a suitable genre for the documentation.

Additional points:


 * Suggest an author/assignee who can/will be working on the task.
 * If you have sufficient expertise in the domain, mention the level of knowledge, technologies, time and effort required to complete the task.
 * Add all necessary tags, like good-first-bug,  javascript,  visualEditor, etc.

Prioritizing
A technical documentation request becomes a priority in the following cases:
 * There are repeated requests from the community to create or improve existing documentation for X.
 * Another process will not work or cannot be completed if X is not documented correctly.
 * The steps outlined for a process are wrong, incomplete or obsolete.
 * The layout of a document makes it difficult or impossible to find important information.
 * X is automated and not updating properly.

Categorizing
The documentation project covers a wide range of requests and hence is categorized into the following boards:

Location
A lot of the technical documentation for Wikimedia project can be found on:
 * Mediawiki.org
 * Wikitech
 * MediaWiki autogenerated documentation

After filing a ticket
It is important to respect the culture and values of an open-source community when using Phabricator. Many people from many places with many different points of view and skill levels will be working together to surface issues and resolve them. Hence, make sure to be thoughtful about the people behind the tasks while interacting with it.

Changing status and priority
It takes time and energy to open a ticket, and equal energy should be spent in evaluating and prioritizing it. In Phabricator, a task is prioritized by assigning status and priority.

Following up
When you file a ticket in Phabricator, you are automatically subscribed to it. You will receive notifications when changes are made to the ticket. It is your responsibility to follow-up, ask questions, clarify, and be aware of the status of the ticket. Many requests for technical documentation end up not being resolved because they are filed with the expectation that "somebody should do something" about it.

Never forget: you are somebody!

Continuous improvement
Technical documentation is never truly finished. Don't hesitate to reopen a closed Phabricator task, if additional improvements are needed. If you are able to edit and feel you have sufficient knowledge to share, you can and should update the documentation.

Closing a ticket
When is technical documentation done? The short answer is: never. However, we can take actions on Phabricator request and close them when we feel there is sufficient technical documentation to complete necessary work. Close tickets when:
 * The requested update or improvement has been made to the technical documentation.
 * New documentation is created, meets the requirements of the technical documentation style guide and has sufficient information to meet the specifications of the ticket.

Examples
Improvement

New doc

Help
For questions or help, contact wikitech-l@lists.wikimedia.org.