Xqt added a comment.
> What do you think is the main role that the documentation of Pywikibot
should fulfill?
- How to install on several environments (Unix, Windows, Toolforge, ...) and
with several sources (git, svn, pypy, nightly)
- A quick start guide, how to use it on local PCs, Toolforge, PAWS
- How to running a bot, including script usage references
- How to writing a bot
- An API reference with examples how to use functions, methods and classes
- How to develop Pywikibot
- Dockumentation, examples and API reference to test environment
- Cross references to MediaWiki API
> What is your general perception of the docs as they are right now? What do
you like and what do you dislike about them? What would you change if you could?
Personally I prefer https://doc.wikimedia.org/pywikibot/master/ and
https://doc.wikimedia.org/pywikibot/stable/ as cental documentation places
because they are created during code integration and reflects the code
documenation as well as doctests. And it is easy to have cross-references and
indexes <https://doc.wikimedia.org/pywikibot/master/genindex.html> as well as
module references <https://doc.wikimedia.org/pywikibot/master/py-modindex.html>
which is created automatically via Sphinx
<https://www.sphinx-doc.org/en/master/>. Unfortunately i18n isn't set up yet.
Another disadvantage is that Sphinx documentation can only be placed via Gerrit.
On the other hand it seems that https://doc.wikimedia.org/pywikibot is not
well known and https://www.mediawiki.org/wiki/Manual:Pywikibot is the prefered
landing page. I am fine with Manual:Pywikibot as a Pywikibot landing page but a
lot of pages behind it is very outdated and I haven't found the time to
syncronize it with the code or the Sphinx documentation. In addition there are
a lot of documentation and how-tos spread over several families (toolforge,
wikidata) and it is not easy to find it. And they also might be outdated due to
missing code references
See also this discussion
<https://www.mediawiki.org/wiki/Project:Pywikibot/Documentation_RFC#pywikibot%20documentation>
about variants of documentation.
> What do you think is the main thing that's missing in Pywikibot's
documentation right now?
Some Phab tasks as well as questions on stackoverflow
<https://stackoverflow.com/search?tab=newest&q=pywikibot> or Topics on
Pywikibot pages indicated that examples are or code snippets would help to use
and understand the usage of the Pywikibot Framework. See also T308063
<https://phabricator.wikimedia.org/T308063> for other examples.
> If you could have active contributors working on something related to
documentation right now, what would that be?
Solving the ambivalence between https://doc.wikimedia.org/pywikibot and
https://www.mediawiki.org/wiki/Manual:Pywikibot, e.g.
- create a maintenance script (using the Pywikibot framework ;-) to
syncronize documentation between these two documentation parts if appropriate
- add references from Manual:Pywikibot to doc.wikimedia.org/pywikibot
- add references from doc.wikimedia.org/pywikibot to Manual:Pywikibot if
appropriate e.g. using //manpage// directive
- cleanup Manual:Pywikibot and move pages to archive if it is outdated and no
longer updated
- merge code examples from Manual:Pywikibot and other locations to Sphinx
documentation
> Pywikibot's documentation is available in multiple places. Which one do you
send people to the most (e.g. when they have questions)? Which documentation is
the most important in your eyes?
I always send links of https://doc.wikimedia.org/pywikibot/master or
repectively /stable in such cases. Also if I introduce new releases I forward
to the changes log. See
https://lists.wikimedia.org/hyperkitty/search?mlist=pywikibot%40lists.wikimedia.org&q=%22New+Pywikibot%22
Thank you @KBach so much.
TASK DETAIL
https://phabricator.wikimedia.org/T312992
EMAIL PREFERENCES
https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: KBach, Xqt
Cc: Xqt, srishakatux, pywikibot-bugs-list, Aklapper, TBurmeister, PotsdamLamb,
Jyoo1011, JohnsonLee01, SHEKH, Dijkstra, Khutuck, Zkhalido, Urstrulykkr,
Viztor, Wenyi, Tbscho, MayS, Mdupont, JJMC89, Dvorapa, Altostratus,
Avicennasis, mys_721tx, jayvdb, Masti, Alchimista
_______________________________________________
pywikibot-bugs mailing list -- [email protected]
To unsubscribe send an email to [email protected]
