Too long; Didn’t read

Much of the content available on Manual:Pywikibot/Scripts (https://www.mediawiki.org/wiki/Manual:Pywikibot/Scripts) and linked script pages is an outdated copy of content already available on doc.wikimedia.org/pywikibot (https://doc.wikimedia.org/pywikibot/master/scripts/index.html). As a result, on-wiki scripts documentation is misleading and confusing, especially to newcomers.

I propose that we clean up on-wiki scripts documentation, by:

• migrating most content to https://doc.wikimedia.org/pywikibot
• marking outdated content as deprecated
• linking directly to doc.wikimedia.org (for example using a template) from the list of scripts and from individual script pages
• only keeping and maintaining a limited number of script documentation pages on mediawiki.org

Long version

Background

As noted in T308063, Pywikibot scripts documentation on mediawiki.org is quite unreliable. This is because on-wiki documentation has to be written from scratch or manually copied from doc.wikimedia.org/pywikibot. A brief look at Manual:Pywikibot/Scripts shows that this doesn’t always happen - there are a lot of red links on that page. Even for pages that exist, it’s difficult to tell whether the documentation is up to date with the current version of Pywikibot.

This is in contrast to the script reference documentation [1] available on https://doc.wikimedia.org/pywikibot/master/scripts/index.html. This documentation is based on in-code docstrings. Apart from introducing a new script, in which case some manual changes to doc.wikimedia.org/pywikibot might be necessary, this documentation is generated automatically from code. As a result, documentation on doc.wikimedia.org/pywikibot is more up-to-date, and more reliable than matching documentation on mediawiki.org.

However, documentation on mediawiki.org provides some benefits over documentation on doc.wikimedia.org:

• Internationalization - doc.wikimedia.org doesn't support internationalization. All descriptions are available in English. On mediawiki.org, some translations are already available, but these translations are common for additional material [2], not for the reference material.
• Documentation on mediawiki.org is easier to edit for non-developers and people familiar with wikis in general. That said, changes to scripts require familiarity with developer tools. Any developer who makes changes to scripts will be able to make the relevant documentation changes on doc.wikimedia.org as well - using the same tools and processes.
• Documentation on mediawiki.org enables users to ask questions for the developers on the Talk page for the script. Example

Proposed solution

With that in mind, I propose the following (for non-compat links and pages):

1. Replace all broken links (17 in total) with links to sections and pages on doc.wikimedia.org/pywikibot.
2. For pages without translations:
   • If the page doesn't provide any content beyond what’s on doc.wikimedia.org (8 pages) - mark the page as deprecated and link to doc.wikimedia.org instead.
   • If the page provides some additional content (9 pages) - migrate that content to doc.wikimedia.org and mark the on-wiki page as deprecated. Link to doc.wikimedia.org.
   • If the page has significant additional content (1 page) - consider moving the content to doc.wikimedia.org and marking the page as deprecated if possible [3]. Link to doc.wikimedia.org if you do.
3. For pages with translations:
   • If the page doesn’t have any additional content (5 pages) - keep the page on wiki but link to doc.wikimedia.org. Remove errors if possible.
   • If the page has some additional content (5 pages) - keep the page, move the content to doc.wikimedia.org and link to doc.wikimedia.org as well. Remove errors if possible.
   • If the page has significant additional content (4 pages) - keep the page, consider moving the content to doc.wikimedia.org if possible. If you do, link to moved content. Try to make improvements to the page as you go.
   • For pages with a lot of translations (15 pages) - keep the page and maintain it on mediawiki.org.

In total, this means:

• Removing 17 broken links
• Improving documentation on doc.wikimedia.org for up to 19 scripts
• Deprecating up to 18 pages
• Adding links to doc.wikimedia.org to 32 pages
• Keeping and maintaining 15 on-wiki pages (3 with considerable additional content, 2 with some, and 10 with no additional content), and maintaining translations of additional 14 on-wiki pages.

For compat pages: leave as is (30 pages) potentially remove or replace 23 red links.

I also propose that we discourage the creation of on-wiki script reference documentation pages that copy the content from doc.wikimedia.org, unless it's for the purpose of translating that content. We could do this, for example, by adding a note to Manual:Pywikibot/Scripts.

Rationale

The proposed solution should make it easier for script users to find reliable documentation by emphasizing doc.wikimedia.org, where the docs are more likely to be up-to-date. It will also preserve the value of translated pages and any additional content created on-wiki, while decreasing the burden of maintaining similar content on multiple platforms.

Data

Attached is a condensed version of my analysis of script pages on mediawiki.org. This analysis includes preliminary recommendations for all script pages.

Alternative solutions

<Placeholder for alternative solutions proposed in the course of discussion in this task. Please feel free to add your proposal (or a link to your proposal in comments or on talk pages) in this section.>

Outcome

I will organize and lead the effort to implement the solution agreed by the community in this task. If my proposal is accepted, this will mean making a plan of necessary activities in Phabricator, organizing an Outreachy project, or similar. Alternative solutions might require a different approach and steps.

---

[1] Reference documentation - for a general explanation, see https://diataxis.fr/reference/. In this particular case, reference documentation is documentation that lists the available scripts, and for each script provides the following information:

• Script name and brief description
• Instructions on how to run the script
• Script parameters
• Expected outcomes of running the script
• Example of script execution (command to run a script + script output) - optional

[2] Additional content/material - any content included in the scripts documentation on mediawiki.org that's not reference documentation as described in [1]. This usually means a tutorial, how-to guide, or extensive examples.

[3] It might not be possible to move specific content to doc.wikimedia.org/pywikibot due to formatting limitations. If that’s the case, the content in question should remain on mediawiki.org