Documentation/Tool docs
This page describes the essential components of basic technical documentation for tools. It focuses mostly on community-created tools, like web apps or bots, which are often (but not always) hosted on Toolforge. The primary audience for this page is tool developers, or other technical contributors who want to help improve tool documentation.
Why document tools?
[edit]Documentation is essential for the usability and sustainability of Wikimedia's tool ecosystem. Docs help people understand how a tool functions and make it possible for them to help maintain it. Writing documentation is a best practice for building a successful tool.
Help tool users:
- Understand what the tool does and how to use it.
- Get started using the tool.
- Find answers to common issues or problems.
- Report issues.
Help other developers:
- Understand the tool's design, expected behavior, dependencies, and how to run it.
- Contribute to the tool.
- Take over maintenance of the tool in the future (if necessary).
- Troubleshoot issues in case of outages.
Help yourself:
- Stay focused while you build your tool. A clear documentation structure can help keep your development work aligned with your tool's core functionality and intended use cases.[1]
- Minimize the amount of user support you do, and receive more useful bugs or issue reports from users.
- Look good! Following development best practices influences how people perceive the quality of a tool; projects with no documentation may be perceived as poor quality or unreliable.
- Maintain your tool in the future. Docs help you remember what you did and why. Your future self will thank you!
What is tool documentation?
[edit]Every tool should have basic user and developer documentation. These don't necessarily need to be separate documents with many pages. The user manual and developer docs should be clearly differentiated, but many tools can accomplish that in a single document with clearly-labeled sections.
| Who is the audience | What is the content | Where are the docs | How to access docs |
|---|---|---|---|
| Tool users | User guide or manual | In the tool's code repository or on a wiki page | From the tool's user interface and in (or linked from) a README file in the tool's root directory |
| Developers | Code comments
|
In the tool's code | Viewing the code in an IDE or on a site like Github. Method/class comments can usually also be accessed by calling the help method for a class or function, and sometimes also by viewing auto-generated documentation pages. |
| Developers | Developer docs | Wikimedia tools should generally use a README and/or a wiki page. | From the tool's user interface and in (or linked from) a README file in the tool's root directory |
In addition to the basic documentation described in the previous section, tools hosted on Toolforge should have:
- A toolinfo record
- A wiki page that uses Template:Tool and is in the
Tool:namespace on Wikitech. You can use this wiki page to publish your docs, or you can just link to your docs from the wiki page.
Get started with a single-page template
[edit]Create essential tool documentation
[edit]User guide
[edit]Your tool's user guide describes why the tool exists, what it does, and how to use it. It may also be called a "manual".
- Who is it for (audience)?
- Tool users
- Where does it live?
- In the tool's code repository or on a wiki page. For tools hosted on Toolforge, publish a wiki page that uses Template:Tool and is in the
Tool:namespace on Wikitech.
- How do people find it?
- From the tool's user interface
- By viewing the tool's code repository
- By viewing a wiki page that documents the tool or links to its docs. Toolforge tools should have a page in the
Tool:namespace on Wikitech. - By viewing tool info in Toolhub
- How long should it be?
- A user guide doesn't need to be many pages! It may only take a few paragraphs to describe your tool's intended use and the basics of how to use it.
- What should it cover?
- How to start and stop the tool.
- What users can do with the tool, and the basic steps for how to do each of those things.
- What users cannot do with the tool - especially if they might think they should be able to do it.
- How to troubleshoot common problems: Think about the five most common things that can go wrong with your tool. What steps could a user take to fix these issues?
- Where and how to report issues with the tool.
- Templates and examples
- InternetArchiveBot's user documentation is multiple pages, organized by task. It provides a clear link to developer docs.
- MoreMenu has a comprehensive single-page user guide on Meta-Wiki, with links to advanced topics and to its code repository.
Developer documentation
[edit]Developer documentation covers topics specific to your application and its code, such as its license, how to run it, and how to contribute.
- Who is it for (audience)?
- Developers, contributors, tool maintainers.
- Where does it live?
- Your license should usually be a separate file published alongside your code. See Pick a license.
- Your developer documentation can be in a single README file in the tool's root directory and/or on a wiki page. Some codebases may have a
/docsdirectory, or README files within subdirectories, but you should still have a README in your root directory to orient people to the code and directory structure when they first arrive at your repository.- Some communities have a convention for using multiple files, like README and CONTRIBUTING, for different pieces of information. If you aren't required to have separate files, make doc maintenance easier by publishing just one document, with clearly-labeled sections for contributing guidelines.
- Toolforge tools can publish docs as a wiki page in the
Tool:namespace on Wikitech.
- How do people find it?
- From the tool's user interface
- By viewing the tool's code repository
- By viewing a wiki page that documents the tool or links to its docs. Toolforge tools should have a page in the
Tool:namespace on Wikitech. - By viewing tool info in Toolforge toolsadmin or Toolhub
- How long should it be?
- This depends on whether your choose to separate your contributing guidelines into a separate file. You can have shorter docs if you separate content into separate README and CONTRIBUTING pages, but then you have to maintain two docs. It's fine to include everything in a single, longer README doc or wiki page. If you choose the single-page approach, just be sure to clearly label your sections, like "Installation and setup" and "How to contribute".
- What should it cover?
- Instructions for setting up the project for development, including any dependencies or special permissions required to run the tool
- How the tool does what it does: For each of the things you wrote down in your user documentation for "what the tool does", describe the basic technical details of how the tool accomplishes those things. Provide links to the relevant functions in your code.
- How developers can contribute code changes to the tool
- Templates and examples
- Single markdown file: Depictor README on Github
- Single wiki page: Wikidata Lexeme Forms provides its user guide and developer documentation on one page with clearly-labeled sections.
- Multiple markdown files: Citation Hunt's README provides overview information, and links to separate contributing guidelines and an additional README for a specific component.
- Multiple wiki pages: Web2Cit includes content for developers on the same page as the user guide. The developer documentation sections are clearly-labeled, and provide links to additional wiki pages with more detailed technical information.
Code comments
[edit]Code tells you how, comments tell you why.—Jeff Atwood, Stack Overflow co-founder[2]
Code comments include:
- Basic contextual information about what a piece of code does, how to use it, and its expected behavior
- References and attribution for code that you copied from elsewhere
- Who is it for (audience)?
- Developers, contributors, tool maintainers. Potentially also infrastructure admins or SREs, depending on where and how a tool runs.
- Where does it live?
- In your code. May be inline comments or method/class comments like header / Javadoc / docstring comments.
- How do people find it?
- Viewing the code in an IDE or on a site like Github. Method/class comments can usually also be accessed by calling the help method for a class or function, and sometimes also by viewing auto-generated documentation pages. Readers should be able to view your code via links from your tool's user interface, and links from any documentation pages on-wiki.
- How long should it be?
- As short as possible while still being clear. Comments that add no useful information actually make your code harder to maintain and read; they add visual clutter and can easily become outdated.
- What should it cover?
- If your code does something non-intuitive, explain why it does that. If you have consciously made a decision that others may find confusing, or which goes against best practices, explain your decision in the comments. You don't need to write comments about code that is simple or obvious, but keep in mind that what is obvious or simple for you may not appear that way to everyone (including future you!).
- If you reused code you found online, add a comment that links to where you found that code. This provides important context and credit to the original creators.[3]
- These guidelines may vary depending on the programming language you're using and the context in which you're developing. Consult the coding conventions or developer guidelines for your programming language, for the software to which you're contributing, and for the infrastructure you're using. For example, the MediaWiki coding conventions include both general and language-specific guidelines for how to document MediaWiki code.
- Templates and examples
- To find templates for the programming language you're using, search the web or consult the documentation for the language itself.
- The diffedit user script uses a code comment to give credit for a function copied from elsewhere.
- Vanderbot: example of a well-documented Python script with comments explaining the functions and purpose of each section, and citations for copied code
Toolforge toolinfo records
[edit]In addition to the basic documentation described in the previous sections, tools hosted on Toolforge should have a toolinfo record. This record displays essential information about your tool in the Toolhub catalog, and helps both users and developers find your tool and its docs.
Help people find your tool docs
[edit]Link to docs from code
[edit]You code comments can only cover a small amount of information. When you want to provide more than a few lines of context or explanation, avoid cluttering your code by putting that longer content in your docs, and link directly to that doc section from a comment in your code.
Add cross-references
[edit]If you maintain your documentation on-wiki, link to the wiki page from a README in your tool's code repository. If you maintain your documentation within your code repository, create a wiki page that links to it.
Wikitech has a Tool: namespace specifically for Toolforge tool documentation, but you should put your tool's docs wherever makes the most sense for you. Many developers prefer to maintain docs as Markdown files with the code, and that is fine, too. By providing cross-references between wiki pages and your code repository, you ensure people will find your docs no matter where you choose to maintain them.
- The Wikidata Lexeme Forms tool has a page on Wikitech, but that page mainly serves as a basic tool record that links readers to the actual location of its documentation on wikidata.org and in its README file.
- The EditGroups tool uses its README file in Github to direct both users and developers to the right docs for them.
Link to docs from your tool interface
[edit]If your tool has a user interface (UI), add links to your user guide and developer documentation (or to your code repository, if your documentation is there). Avoid duplicating the same content in your documentation and your tool's UI.
- Locator-tool includes basic usage instructions within the tool UI, and links to additional user help on-wiki
- Depictor and CitationHunt both link to their source code from the tool UI, and provide links in the README file to user guides or other technical docs.
List doc URLs in toolinfo record
[edit]When you add your tool to Toolhub or create your toolinfo record, help people find your docs by filling in the user_docs_url and developer_docs_url properties. For example, see the CitationHunt toolinfo.json file, which links to the user docs on Meta-Wiki:
{
"user_docs_url" : [
{
"url" : "https://meta.wikimedia.org/wiki/Citation_Hunt",
"language" : "en"
}
]
}
The toolinfo doc URL properties render as links in the "Usage" and "Contributing" sections of the tool's record in the Toolhub UI:
Full list of examples
[edit]The table below lists all the tools this page uses as examples, with links to their user and developer documentation. Thanks to the maintainers and contributors who created documentation that exemplifies the many options, formats, and platforms for publishing tool docs.