Project:Pywikibot/Documentation RFC

pywikibot documentation
This is an initial braindump on issues with the current pywikibot documentation and possible solutions, by Valhallasw (talk) 19:49, 20 May 2014 (UTC).

Current issues

 * 1) The documentation is spread out. There is the documentation here on mw.org, but also documentation on basically every Wikipedia (e.g. nl:Help:Gebruik_van_bots), every wikibook and even on wikiversity. Then there's also botwiki: and various guides on wikia. There should be only one authoritative and comprehensive place for users to go for help.
 * 2) The documentation is outdated. The wikia links above are the worst (Python 2.3 and CVS), but even more recent documentation is only valid for compat, and often documentation does not clarify for which version it was written. The documentation is rarely updated by developers.
 * 3) The documentation lacks structure. This is, of course, a direct result of the wiki structure. People add a page to write down what they did, instead of trying to merge it into the central documentation, or they add documentation in a section it doesn't really belong.
 * 4) There is no API documentation

The good things
There are also some things awesome with the current documentation:
 * 1) It's really easy to contribute: anyone with an mw.org account can edit/improve a page;
 * 2) Documentation can be translated relatively easily (which is important)
 * 3) Documentation is in a sensible location -- the same place as MediaWiki documentation.

What can we do?
To tackle the 'bad' points mentioned above, I think there are a few things we should get:


 * 1) Curation: developers need to take an active role in curating content added to the documentation by others (spread out; outdated; structure)
 * 2) Developers need to take an active role in keeping documentation up to date (spread out; outdated)
 * 3) Some sort of automated documentation generation (outdated; API docs)

However, we should do that without losing the good points mentioned above.

Options
A few possible options:

Suggestions from pywikibot gold-standard evaluation
As a part of the gold standard evaluation for pywikibot, I identified several documentation-related issues: API:Client code/Evaluations/Pywikibot. --Fhocutt (talk) 19:07, 25 July 2014 (UTC)

Changes that would improve the documentation include:
 * Add code samples to the documentation to provide easy-to-use examples for common tasks (including queries/lists/searches and edits)
 * Add easy-to-find, complete, and intuitive installation instructions to the documentation. This should include installation via pip (https://bugzilla.wikimedia.org/show_bug.cgi?id=65176) and into virtual environments (https://bugzilla.wikimedia.org/show_bug.cgi?id=61783).
 * Add documentation for people who aren't running bots with existing scripts (particularly researchers who extract data via the API and beginning/intermediate bot writers).
 * Method docstrings should include a link to the corresponding API subpage.