Greetings!
The Wikimedia Technical Documentation team https://www.mediawiki.org/wiki/Wikimedia_Technical_Documentation_Team has built several new tools to help you write with confidence, and identify opportunities to improve docs.
Write with confidence: use automated documentation linting to check your prose
Writing good technical documentation can be difficult! To make it easier, we built documentation linting tools that provide sentence-level suggestions to help simplify your prose, avoid confusing language, and align your writing with the documentation style guide https://www.mediawiki.org/wiki/Documentation/Style_guide.
-
Visit https://techdoc-linter.toolforge.org/ to use the documentation linter as a stand-alone tool (works with mediawiki.org and Wikitech pages) -
Get doc suggestions in your local text editor or IDE https://gitlab.wikimedia.org/repos/technical-documentation/documentation-linting/linter-quickstart#how-to-use-vale-to-lint-documentation-in-your-text-editor-or-ide -
Run the doc linter on your project in a GitLab CI job https://gitlab.wikimedia.org/repos/technical-documentation/documentation-linting/linter-quickstart#how-to-use-vale-in-a-gitlab-ci-pipeline -
Learn more about the documentation linting tools https://www.mediawiki.org/wiki/Documentation/Tools/Linting
We hope these tools help you feel empowered and more confident in your ability to write high-quality technical documentation.
Identify opportunities to improve docs: get metrics to direct your efforts
Measuring the quality of technical documentation is complicated, and the volume of content can make it hard to know where to focus your efforts. Readers often navigate docs as groupings of related pages, so analyzing metrics across pages can provide valuable insights. To help with this, we built tools that provide metrics for collections of technical documentation:
-
The technical documentation dashboard https://www.mediawiki.org/wiki/Documentation/Tools/Documentation_metrics_dashboard displays aggregate data for collections of pages on mediawiki.org, Wikitech, and Meta-Wiki. Use it to get a unified view of doc statistics across pages, and drill down to view data for individual pages.
-
The metrics generator https://www.mediawiki.org/wiki/Documentation/Tools/Metrics_generator provides specialized metrics for collections of technical documentation on mediawiki.org. Use it to assess key quality indicators of tech docs, and identify pages to focus on.
We hope these tools make it easier to prioritize and measure documentation improvements across multiple technical wiki pages. Try using the metrics generator and technical documentation dashboard to identify pages to improve, then run the linting tools on those pages to get writing suggestions.
Tell us what you think!
These tools are experimental and have much room to grow. Please give us your feedback! We'd especially like to hear about:
-
How do you use these tools, and how do they help you? -
What other types of tooling or data would help you contribute to improving Wikimedia technical documentation?
Provide feedback at https://www.mediawiki.org/wiki/Talk:Documentation and join #wikimedia-techdocs on IRC for discussion. Thank you for caring about technical documentation!
-Tricia, on behalf of the Wikimedia Technical Documentation team
On 06/23 09:21, Tricia Burmeister wrote:
Greetings!
The Wikimedia Technical Documentation team https://www.mediawiki.org/wiki/Wikimedia_Technical_Documentation_Team has built several new tools to help you write with confidence, and identify opportunities to improve docs.
Write with confidence: use automated documentation linting to check your prose
Writing good technical documentation can be difficult! To make it easier, we built documentation linting tools that provide sentence-level suggestions to help simplify your prose, avoid confusing language, and align your writing with the documentation style guide https://www.mediawiki.org/wiki/Documentation/Style_guide.
Visit https://techdoc-linter.toolforge.org/ to use the documentation linter as a stand-alone tool (works with mediawiki.org and Wikitech pages)
Get doc suggestions in your local text editor or IDE https://gitlab.wikimedia.org/repos/technical-documentation/documentation-linting/linter-quickstart#how-to-use-vale-to-lint-documentation-in-your-text-editor-or-ide
Run the doc linter on your project in a GitLab CI job https://gitlab.wikimedia.org/repos/technical-documentation/documentation-linting/linter-quickstart#how-to-use-vale-in-a-gitlab-ci-pipeline
Learn more about the documentation linting tools https://www.mediawiki.org/wiki/Documentation/Tools/Linting
We hope these tools help you feel empowered and more confident in your ability to write high-quality technical documentation.
Identify opportunities to improve docs: get metrics to direct your efforts
Measuring the quality of technical documentation is complicated, and the volume of content can make it hard to know where to focus your efforts. Readers often navigate docs as groupings of related pages, so analyzing metrics across pages can provide valuable insights. To help with this, we built tools that provide metrics for collections of technical documentation:
The technical documentation dashboard https://www.mediawiki.org/wiki/Documentation/Tools/Documentation_metrics_dashboard displays aggregate data for collections of pages on mediawiki.org, Wikitech, and Meta-Wiki. Use it to get a unified view of doc statistics across pages, and drill down to view data for individual pages.
The metrics generator https://www.mediawiki.org/wiki/Documentation/Tools/Metrics_generator provides specialized metrics for collections of technical documentation on mediawiki.org. Use it to assess key quality indicators of tech docs, and identify pages to focus on.
We hope these tools make it easier to prioritize and measure documentation improvements across multiple technical wiki pages. Try using the metrics generator and technical documentation dashboard to identify pages to improve, then run the linting tools on those pages to get writing suggestions.
Tell us what you think!
These tools are experimental and have much room to grow. Please give us your feedback! We'd especially like to hear about:
How do you use these tools, and how do they help you?
What other types of tooling or data would help you contribute to improving Wikimedia technical documentation?
Provide feedback at https://www.mediawiki.org/wiki/Talk:Documentation and join #wikimedia-techdocs on IRC for discussion. Thank you for caring about technical documentation!
-Tricia, on behalf of the Wikimedia Technical Documentation team
Wikitech-l mailing list -- wikitech-l@lists.wikimedia.org To unsubscribe send an email to wikitech-l-leave@lists.wikimedia.org https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
This is awesome!
Thanks a lot for working on this, I'll do some trials, but I want to enable it in all the toolforge/cloud repos if possible :)
A bit side-question, is there a recommended way of publishing docs from git repos to wikitech? (that would enable a lot of workflows for us that currently need to do manually to make sure things are still in sync).
On Tue, Jun 24, 2025 at 7:15 PM David Caro wrote:
This is awesome!
Thanks a lot for working on this, I'll do some trials, but I want to enable it in all the toolforge/cloud repos if possible :)
Thanks! Please let us know if we can help in any way, or if you find any bugs or issues.
A bit side-question, is there a recommended way of publishing docs from git repos to wikitech? (that would enable a lot of workflows for us that currently need to do manually to make sure things are still in sync).
I don't think we have a standard mechanism for publishing docs from repos to wikitech. But I'm always on the lookout for docs automation opportunities. Let's discuss this!
wikitech-l@lists.wikimedia.org