Technical documentation prioritization

Overview
This page is evolving. 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. The "somebody should do something" model for getting documentation done does not work, and we must move beyond it.

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

Requests regarding technical documentation in Phabricator
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.

Learn how to file a ticket in Phabricator.

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


 * 1) You know there is something in the technical documentation that requires a fix or improvement, and you don't know how to fix or improve it. You are asking the technical community for help, you are willing to follow up on your request, and 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 know there is something in the technical documentation that requires a fix or improvement. 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 the updates can be made.

For new documentation:



For existing technical documentation

 * 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.

For new technical documentation requests

 * 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.

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.

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