User:Vidya Srivatsan/Sandbox

Overview
There should be an assessment tool or set of guidelines to help categorize and prioritize requests for new and improved technical documentation. It is time to move beyond the model, in which a problem is pointed out or a request made and no action is taken.

Priorities
What makes a piece of technical documentation a priority? (In no particular order, yet):


 * There are repeated requests from community and staff to create or improve existing documentation for X
 * A process will not work or cannot be completed if X is not documented correctly
 * The steps outlined for a process are wrong or incomplete
 * The information about X is wrong or out of date
 * The organization of a document makes it difficult or impossible to find important information
 * X is automated and not updating properly

Assessment tool for technical documentation
To help user categorize and prioritize their request for technical documentation,  Wikimedia has come up with an assessment tool called Wikimedia's Phabricator instance in the #documentation project.

Learn how to file a ticket in Phabricator.

What to include in your Phabricator ticket
The issues or request that are raised in Phabricator can be broadly classified into three different categories:

For existing technical documentation

For new technical documentation

Authors or Assignees who will work on your request

Consider the following parameters for each category:

When to file a request for technical documentation ticket in Phabricator
For improvements and fixes:

The following instances may be considered when you know there is something in the technical documentation that requires a fix or improvement

1.   You are asking the technical community for help and you are willing to follow up on your request. If the documentation is in a place where you can make edits, you are willing to update it based on the information other technical collaborators share.

2.  You do have an understanding of how to fix or improve it. However, you are unable to make the updates yourself. You are willing to share what you know with other technical contributors, so someone can update it.

For new documentation:

The following instances may be considered for new documents:


 * 1) You are asking the technical    community for help on what information to be included for different genre     of documents?
 * 2) You have the information for    different genre of documents but you do not know how to or where to place     those information in the document.



Following up on requests for technical documentation in Phabricator
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!

When is technical documentation done?
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:


 * 1) The requested update or improvement has been made to the technical documentation.
 * 2) New documentation is created, meets the requirements of the technical documentation style guide and has sufficient information to meet the specifications of the ticket.

Changing ticket status in Phabricator
When working in Phabricator it is important to respect the culture and values of an open source community. Many people from many places with many different points of view and skill levels will be working together to surface issues and resolve them. It takes time and energy to open a ticket, and equal energy should be spent evaluating and prioritizing it. Be thoughtful about the people behind the tasks.


 * Resolved - Use this if the ticket is truly resolved.
 * Stalled - There has been no traction on this ticket in a long time. What can we do to get it moving?
 * Declined - Avoid using this, unless a task is truly not possible. Consider moving ticket to lowest priority.
 * Invalid - Use this only if the request is not actionable in anyway.

Criteria for prioritizing a ticket

 * Unbreak Now - Rarely if ever needed for technical documentation
 * Needs Triage - Ticket starts out here. Set one of the below priorities, once the task is understood.
 * High - Issues that are blocking folks from completing tasks or understanding how to complete them, super quick fixes -- if it will only take a few min to update
 * Normal - Requests for new documentation or improvements, which will greatly improve user experiences
 * Low - Requests for new documentation or improvements, which would be nice to have
 * Very Low - older requests, which are not well defined or do not present a blocker

Note: The above priorities are focused around the documentation and task, not when someone plans to complete it, which is another method of prioritization used on Phabricator: Phabricator/Project management

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.

Need help?
For questions or help, contact wikitech-l@undefinedlists.wikimedia.org.

See
Much of the technical documentation for Wikimedia project can be found on two Wikis


 * https://wikitech.wikimedia.org/wiki/Main_Page
 * https://www.mediawiki.org/wiki/Documentation

Phabricator documentation: Phabricator/Help