Jump to content

Documentation/Tool docs

From mediawiki.org

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.

Overview of basic tool documentation
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
  • Inline comments
  • Method and class header / Javadoc / docstring 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

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 /docs directory, 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.
Don’t duplicate documentation between your README and any wiki pages you create for your developer documentation. Duplicate information is hard to maintain, and can be confusing for readers. Instead, use cross-references.
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

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.

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]
[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.


TODO: Find and add a nice example of this from some real code and real docs.


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.

MediaWiki.org has some templates that support linking from wiki pages to code.

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.

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

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:

A tool record in Toolhub showing hyperlinks to developer and user docs
Screenshot example of toolinfo documentation properties displaying in 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.

Tool User guide Developer docs Sample code comments Toolhub record
Citation Hunt single page on Meta-wiki multiple files on Github Comment explaining table usage and linking to Phabricator task https://toolhub.wikimedia.org/tools/citationhunt
Depictor single page on Commons with link to video tutorial README on Github https://toolhub.wikimedia.org/tools/hay-depictor
diffedit single page on Meta-wiki Example of a code comment giving credit for a function taken from elsewhere
EditGroups single page on Wikidata Generated doc website from files stored with code (for developers/contributors), and a basic page on Wikidata for developer end-users. README with clear links to user and developer docs. https://toolhub.wikimedia.org/tools/toolforge-editgroups
InternetArchiveBot multiple pages on Meta-wiki single page on Meta-wiki
LocatorTool single page on Commons and About page in web app multiple files on Github https://toolhub.wikimedia.org/tools/locator-tool
MoreMenu single page on Meta-wiki README on Github Example of a comment explaining the reasoning behind what may appear to be a counter-intuitive decision. https://toolhub.wikimedia.org/tools/metawiki-musikanimal-moremenu
VanderBot README on Github with links to blog posts for more information README on Github A nicely-commented Python script with comments explaining the functions and purpose of each section, and citations for copied code https://toolhub.wikimedia.org/tools/vanderbilt-vanderbot
Web2Cit multiple pages on Meta-wiki multiple pages on Meta-wiki https://toolhub.wikimedia.org/search?q=web2cit
Wikidata Lexeme Forms cross-reference page on Wikitech

single page user guide on Wikidata

README on GitLab with links to API section of Wikidata page https://toolhub.wikimedia.org/tools/toolforge-lexeme-forms

References

[edit]