Doc Your Tool: Creating user-friendly documentation/Instructions

Instructions for how to work on improving tool docs during the Doc Your Tool project at the 2024 Hackathon.

Find a tool to document

1. Go to Toolhub.
2. Browse tools or use the search to look for tools in areas that interest you.
3. Click on a tool to view its full record.

Verify that the tool welcomes contributions

In the tool's record in Toolhub, look for the "Contributing" section and click the links there.

• If there's only a link to the tool's repository, look in the README file for information about how to contribute, or look for a separate file named CONTRIBUTING.
• If the README contains a link to documentation on a wiki, check that documentation to see if there are contributing guidelines there.

If you can verify that the tool's maintainer(s) welcome contributions, move on to the next step. If you're not sure, you can try to message or contact the maintainers to ask them if they'd welcome documentation help, or you can look for a different tool to work on.

Review the tool's docs

After you verify that a tool you're interested in documenting welcomes such contributions, start to review the existing docs. If this is a new tool or there's no documentation at all, jump to Write or edit docs.

The user guide and developer docs may not always be separate documents, and that's okay! What matters is that you can clearly identify which pieces of information are for users, and which are for developers.

User guide

When viewing a tool's record in Toolhub, check the following:

Does the tool have a link in the "How to use" field?

Screenshot example of toolinfo documentation properties displaying in Toolhub UI

• If the tool doesn't have a link in the "How to use field": can you find whether a user guide actually exists for the tool?
  • In the Toolhub record, check the source repository link: there may be a README in the tool's repository that contains the user guide, or links to where to find it.
  • If the tool is a web app or has a user interface: check if there are links to documentation from there.
  • If you find a user guide, edit the tool record in Toolhub to add the link in the field labeled "User docs URL".

Screenshot of Toolhub UI for adding documentation links

• If the tool already has a link in the "How to use" field (or, if you just added the link): check if the linked documentation covers the basic elements of a user guide.
  • Approach the documentation as a new user: with the information provided, can you understand what the tool does, who can use it, and how to get started using it?
  • Note anything that is missing, or parts of the user guide that are confusing, then move on to reviewing the developer documentation.

If the tool doesn't have a user guide, and you can't find one after searching: you can write one! Move to the next section, or jump to Write or edit docs.

Developer docs

Go back to the tool's record in Toolhub:

• If there's a link in the "Developer Documentation" section, use that link.
• Otherwise, click the link or button to view the tool's repository or source code.

When viewing the tool's source code, check the following:

• Is there a README, or developer documentation on a wiki page?
  • If you can't find any developer documentation: move to the next section: Write or edit docs.

If there is a README:

• First, check for cross-references to other key docs:
  • Does the README link to the user guide? If not: edit the README to add a link to the user docs.
  • Is the README in the source repository the main developer documentation, or is it just a placeholder that points to developer docs that are elswhere (like on a wiki page?)
    • Make sure there are links in both directions between any on-wiki documentation you find, and the README in the tool's source repository.

After you identify the primary location of the tool's developer documentation (in the README or on a wiki page, or somewhere else), and you've ensured there are links between the repository and any docs published elsewhere, review the contents of the developer docs:

• Use the Tool Docs Guide as a reference as you review the developer docs to see if they contain the essential information.
• Does the documentation include instructions for how to install, configure, and run the tool?
  • If you follow those instructions, do they work? Can you successfully run the tool locally? Note anything that is missing, or parts of the documentation that are confusing.
• Does the developer documentation include guidelines for how to contribute?
  • If not, is there a separate CONTRIBUTING file in the repository?
• Does the developer documentation include a section for how to get help?
  • If not, is that information available anywhere else, like in the user guide, or linked from the Toolhub record, or in the tool's UI?

Write or edit docs

In the previous step, you gathered information about what is missing from the tool's documentation, what could be improved, and links that could be added to help users find information more easily. Now, it's time to write or edit content to help improve the docs.

1. Use the Tool Docs Guide to identify the essential pieces of information that each type of tool doc should contain, and find templates and examples to help with your writing. Try to use the tool and/or run the tool locally, and use what you learn to write or edit the documentation.

If you're documenting a new tool, or a tool that doesn't yet have any documentation, use the basic tool doc template to help you get started.

1. If the documentation is on a wiki page, login to the wiki and edit the page. When you save your changes, you can note that you're making doc improvements as part of the Doc Your Tool Hackathon project.
2. If the documentation is in a code repository, follow the standard procedure for contributing code changes to that repo. Here are the Wikimedia Gerrit instructions and Gitlab instructions . If you are entirely new to Wikimedia development, start here .

Get feedback or review

Ask someone else to read what you wrote and give you feedback on whether it is clear and understandable. If you sent a patch for review, you can get this feedback from the code reviewer, but if you published your changes on a wiki page, you may need to explicitly ask someone for feedback.

Record your work

To help track the work that was done as part of this Hackathon project, add a comment on the Discussion page for this project. Include in your comment:

• The name of the tool you worked on
• A link to the tool's Toolhub record
• A link to your change, or to your new content on a wiki page.
• A brief description of the type of documentation improvements you made.

Mission accomplished: you're a documentation superstar!