Plugins should have user documentation outside the plugin itself so that potential users can learn about the plugin without installing it. A common way to do this is to create a plugin wiki page on the Jenkins wiki.
Plugin wiki pages should be organized as child pages of the Plugins page. Go to that page, be sure to be logged in, and click Create in the page header. The page you’ll create will automatically be added as a child of the Plugins page.
Use the {jenkins-plugin-info:pluginId=YOUR-ARTIFACT-ID} macro near the top of your plugin’s wiki page.
It will link to the plugin’s page on the plugin site, as well as any security warnings applicable to the plugin to warn users.[1]
The wiki page should contain basic documentation that explains what the plugin does, and how to configure it in Jenkins. This documentation should be kept up to date as the plugin changes. Note that it is best to keep the documentation as a whole in mind when amending it: For example, don’t just add new sections at the bottom when you add new features, but write the documentation so that someone new to the plugin has the best experience reading the documentation.
Include a changelog that shows the changes in every version you release. Keep in mind that many Jenkins users are not necessarily Java developers, so focus on the effect of a change to users, rather than exactly what code you changed. People can always read the source code if they want to know exactly what was changed.
If a plugin links to its wiki page from its metadata (defined using the <url> tag in the pom.xml), the plugin site will scrape the wiki and include the page contents directly.
If a non-wiki URL is specified, for example to a GitHub repository, it will only show a link instead.
Given the limitations inherent in including scraped content, many advanced macros will not show up properly on the plugin site: Basically every macro that uses AJAX to load data in the background will not work. Since Jenkins will link to the plugin’s page on the plugin site from its plugin manager, this will result in a bad experience reading broken documentation for many users.