User:Pavithraes/Sandbox/Technical documentation prioritization

Overview
An attempt to improve the process of categorization and prioritization of technical documentation requests on Phabricator. A set of guidelines have been outlined to help us move beyond the "somebody should do something" model, which does not seem to work.

Documentation Tag
Technical documentation is a broad project that covers everything from contribution guidelines to communication etiquettes, hence the documentation workboard has multiple boards for organizing the tasks.

Filing a technical documentation request
Requests for improvements and new technical documentation and issues with automated documentation can be done by filing a ticket in Wikimedia's Phabricator instance in the #documentation project.

A technical documentation request is filed for the following reasons:


 * 1) An existing document has errors that need to be fixed
 * 2) An existing document needs to be updated
 * 3) A new document needs to be created

When should you file a ticket?
You should file a technical documentation request if you understand that there is a need for an improvement, update error-fix in an existing document or creation of new document. Here are a few guidelines based on the type of user filing the request:

You do not know how to fix/improve/write the doc:
 * Be willing to follow up on your request
 * Be willing to make certain updates based on information you get by other technical collaborators

You know how to fix/improve/write the doc however you are unable to do so yourself:
 * Be willing to share what you know
 * Be willing to follow up and aid the contributor in writing the doc

You know how to and are able to:
 * Be willing to open a task and assign it to yourself
 * Communicate with the other contributors and ask for feedback

Categorizing, which board
You are required to categorize the request into the followng boards:
 * Backlog
 * New technical documentation requests
 * Update or improvement needed to existing documentation
 * Organize or reorganize technical documentation
 * Completed, blocked, wrong category, refinement needed, or older needs review
 * Meta resources, standards, and tools for technical documentation
 * Multimedia requests for technical documentation
 * API Documentation requests
 * ORES and JADE documentation requests
 * Automated and inline technical documentation
 * Process and planning documenation

Location
For new documents:

Tags?
Use the Documentation tag along with any other. Add necessary subsribers.

Existing docs

 * What is the problem? Is the information wrong? Are there steps missing? Have interfaces or options changed?
 * What information do you need to know in order to make the information complete?
 * Where is the problem? Provide a link to the page or section that needs to be updated.

New docs

 * Where should it go? Ideally you can provide a location and title.
 * Why is it important?
 * What information should be included?
 * What genre of document would you like created?

Authors/Assignees

 * Who will fix or create the technical documentation?
 * Is it something that you can update or share information about?
 * What level of knowledge or skill do you think someone might need to complete this task? This helps individuals to identify who might be able to complete the work on this ticket, if you cannot.

Changing status
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.

Changing Priority

 * 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

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.