User:Pavithraes/Sandbox/Technical documentation prioritization
 | This page has been merged to Documentation/Technical documentation prioritization |
Overview[edit]
The Documentation project on Phabricator is used to track technical documentation tasks 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[edit]
Requests for improvement of existing documentation, creation of new documentation and issues with automated documentation can be filed in Wikimedia Phabricator under the #documentation project tag.
Use this form to create a request ("task").
Task Content[edit]
A complete and unambiguous description of tasks is important for effective task tracking. The following are some points to consider while writing your task description.
For existing docs:
- Clearly describe the problem. Some examples of documentation problems are: 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 list out 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 or 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.
- Optionally add further related project tags, like good-first-bug, javascript, VisualEditor, etc.
Prioritizing[edit]
A technical documentation request becomes a priority in the following cases, where X can be any project, task, process or tool.
- There are repeated requests to create or improve the documentation for X.
- The complete documentation of X is required for another process to work, or another task to be completed.
- The steps described for X (a process) are wrong, incomplete or obsolete.
- The structure/layout of information in the documentation of X makes it difficult to find important information.
- X is auto-generated and is not updating properly.
Categorizing[edit]
The documentation workboard in Wikimedia Phabricator covers technical documentation requests across the various Wikimedia projects. Hence, requests are categorized into the following workboard columns:
- Backlog
- New technical documentation requests
- Update or improvement needed to existing documentation
- Organize or reorganize technical documentation
- 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 documentation
- Completed, blocked, wrong category, refinement needed, or older needs review
Location[edit]
A lot of Wikimedia's technical documentation can be found at the following locations:
| Location | Description | Edit privilege |
|---|---|---|
| MediaWiki.org |
Documentation related to the installation and configuration of MediaWiki. Also includes:
|
Anyone can edit. Log In not required. |
| Wikitech | Documentation related to the technical projects and infrastructure maintained by the Wikimedia Foundation | Wikimedia developer account required. No anonymous edits. |
| MediaWiki autogenerated documentation | MediaWiki developer documentation. Information about the implementation of tools and libraries in core. | Requires contributions to the code base. |
After filing a task[edit]
It is important to respect the culture and values of an open-source community while using Phabricator. People from many places with different points of view and skill levels work 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[edit]
It takes time and energy to open a task, and equal energy should be spent in evaluating and prioritizing it. In Phabricator, a task is prioritized by assigning a status and priority.
Following up[edit]
When you file a task in Phabricator, you are automatically subscribed to it and you will receive notifications when changes are made to the task. As the author of the task, it is your responsibility to:
- Monitor the status of the task and the changes made to it.
- Follow up on the task regularly.
- Be open to feedback from the community and work with other collaborators to complete the task.
Continuous improvement[edit]
Technical documentation is never truly finished. There is always scope for improvement, updates and additions. Feel free to create follow-up tasks if additional work is needed. Make sure to communicate with the author and take responsibility for the proposed improvements.
Closing a task[edit]
Even though technical documentation is never fully complete, we can close Phabricator tasks by setting their status to "Resolved" when there is a consensus that the documentation is satisfactory and sufficient.
We can close tasks as "resolved" when:
- The requested update or improvement has been made to existing technical documentation.
- New documentation is created that meets the requirements of the technical documentation style guide and meet the specifications of the task.
Examples[edit]
- Improving existing documentation: phab:T203858
- New documentation request: phab:T157241
- In the following custom example, note that:
- the #documentation tag has been added.
- target audience has been mentioned.
- time and technologies required have been specified.
- useful resources and related tasks have been included.
- the task has been assigned a Low priority because the request is nice to have.
Help[edit]
If you have queries or need help, contact: