This page provides guidelines on how to file useful and thorough documentation tasks in Phabricator.
Before you file a task
Can you fix the documentation issue yourself? Wikimedia technical documentation relies on everyone to contribute improvements. If you notice something is wrong, be bold and edit the wiki page or send a pull request to the project maintainers to update the documentation.
If you can't fix the documentation issue yourself:
- Option 1: comment or ask a question on the Discussion page for the specific document.
- Option 2: file a Phabricator task about it. The Documentation project on Phabricator is used to track technical documentation tasks across Wikimedia spaces. This tag contains many tasks of varying levels of scope and difficulty. To avoid filing duplicate tasks, search for existing documentation tasks that include your issue before you file a new one.
Filing a technical documentation task
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 report a bug in documentation. Use this form to propose additional documentation.
Task Content
A complete and unambiguous description of tasks helps with 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 task, javascript, VisualEditor, etc.
After filing a task
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.
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.
Examples
- 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.
