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 [[ https://www.mediawiki.org/wiki/Manual:Pywikibot/watchlist.py | 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 [[ https://gerrit.wikimedia.org/r/plugins/gitiles/pywikibot/core/+/HEAD/scripts/watchlist.py | 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**
* https://www.mediawiki.org/wiki/Project:Pywikibot/Documentation_RFC
* {T288833}