Some observations while developing workshop materials around Pywikibot as part of the Small-Wiki-Toolkits initiative:
Docs targeting bot users
https://www.mediawiki.org/wiki/Manual:Pywikibot/Scripts
- Documents kept only for historical purposes are still linked from the "scripts" page.
- Some pages do not demonstrate the use of essential parameters / arguments well
- The watchlist script documentation says "there appears to be no arguments which can be used with it. Just type python pwb.py watchlist. However the syntax example in scripts/watchlist.py has this python pwb.py watchlist [-all | -count | -count:all | -new]. Though command line flags are technically different from command line arguments, can this made more explicit?
- Some pages still use options or parameters that are deprecated
- Some scripts are even missing pages and still appear in red links on the landing page
- Scripts categorization needs a review and overhaul. For example, some scripts that do category work (e.g., 'category.py') are placed under the "Main bot scripts" section when they should be under the "Categories" section.
Docs targeting bot developers
- Code samples need a review.
For example, Pywikibot as a library page has https://doc.wikimedia.org/pywikibot/master/ a syntax error in the code sample (https://doc.wikimedia.org/pywikibot/master/library_usage.html). __main should be __main__, line 26 should be options not args - Need simple documentation for bot writers. As an example, the following page includes a basic script for building new scripts (but it is nowhere near to simple and can be further broken down into smaller modules): https://www.mediawiki.org/wiki/Manual:Pywikibot/Create_your_own_script
- Need more code samples around available classes and methods on MediaWiki.org.
See also