Documentation/Contribute/Filing documentation tasks

From mediawiki.org

This page provides guidelines on how to file useful and thorough documentation feedback and requests on wiki pages or as tasks in Phabricator.

Before you leave a comment or file a task[edit]

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. Use Documentation resources like templates and style guides to help guide your writing and revisions.

What to include in your documentation comment or Phabricator task[edit]

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

Reporting issues with existing docs[edit]

  • Clearly describe the problem. What were you trying to do when you visited this document, and what problem did you face? What information was missing or incorrect? What was confusing or misleading?
  • If possible, specify the exact location (page, paragraph) of the problem. Provide links or quote the exact section that needs work.
  • If possible, provide links to information or references that would help someone to improve the documentation or address the issues you're noting in your task.

Filing requests for new documentation[edit]

  • Define the purpose of the new document and list what it should cover. Refer to document templates to help you identify the type of document you think should be created. For introductions or overview documents: What should the reader understand after they read the document? For how-to or user guide documents: what should the reader be able to do (what task can they accomplish?) with the help of the document?
  • Define the audience of the new document.
  • Suggest a location and title for the document.
  • Provide references to resources that would help someone create the document, and to pages that are important to link from the new document.
  • If you have sufficient expertise in the domain, estimate the level of knowledge, technologies, time and effort required to complete the task.
  • Optional: add tags, like good first task, javascript, VisualEditor, etc.

After filing a task[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. Follow Bug_management/Phabricator_etiquette and understand that in a complex open-source ecosystem, there are many open tasks and many factors that influence what gets worked on, and by whom.

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.