- Review and update the landing page (see subtask T304756)
- Review existing phab tasks:
- Assess the content area and describe:
- your process: what was a fruitful assessment technique, and what was a dead end?
- your findings: what are the most needed improvements in this set of docs, and how would you group those improvements into related tasks? how much overlap is there between the priority improvements in your assessment vs. what is already tracked in phab tasks or mentioned on Talk pages?
- Plan with @srishakatux and other stakeholders how to turn the output of this work into an Outreachy project for September 2022, with the intent of having a clearly scoped set of work to improve Pywikibot collection starting in December.
Description
Description
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Resolved | TBurmeister | T312997 Assess data access doc collections | |||
| Resolved | KBach | T312992 Assess Pywikibot docs collection | |||
| Resolved | KBach | T304756 Review Pywikibot landing page |
Event Timeline
Comment Actions
Please take into account that most of the documentation is autogenerated and Xsan be found at https://doc.wikimedia.org/pywikibot/master/
Comment Actions
Good question - it's a reminder to myself that this documentation is static html located on some server and is not directly editable like a wiki page would be. Sphinx works in a way that strongly resembles static site generators like Hugo, Jekyll, and the like, so I thought it's a good distinction to make. If you think there's a better way to differentiate that documentation from what's on wikis, please let me know! Maybe it's enough to say that it's on doc.wikimedia.org?
Comment Actions
If you think there's a better way to differentiate that documentation from what's on wikis, please let me know! Maybe it's enough to say that it's on doc.wikimedia.org?
Don't know what the right word would be. You cannot edit it like a wiki but you have to change the code repository where the documentation resides.
Comment Actions
Hi @Xqt, as I'd mentioned on your talk page, here's a few questions I had about Pywikibot docs. I realize they might be a bit broad, but I'm trying not to make any specific assumptions about this task and about docs in question.
- What do you think is the main role that the documentation of Pywikibot should fulfill?
- 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?
- What do you think is the main thing that's missing in Pywikibot's documentation right now? If you could have active contributors working on something related to documentation right now, what would that be?
- 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?
Please feel free to provide as short or long answers as you like. You can post them here or send them to me directly (contact details on my user page). I really appreciate your help, thank you!
Comment Actions
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 as well as module references which is created automatically via Sphinx. 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 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 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 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.
Comment Actions
@Xqt thanks again for sharing your thoughts on this.
I have now put together a short list of conclusions from my analysis of Pywikibot docs here: https://www.mediawiki.org/wiki/User:KBach-WMF/Collections/PywikibotCollection/Analysis - this page also contains a few proposals and next steps that I believe would make the docs easier to maintain and more useful, especially for newcomers. As I indicate on that page, I should have time to work on these recommendations myself until end of this year.
I would appreciate any feedback you can provide on these conclusions and proposals. I want to make sure that any changes I make to Pywikibot docs over the coming weeks align with what you and the community think makes most sense.
I am also resolving this task. Any follow-up work will be handled in T320625.
(Also, for my conclusions about collections in general (outside the Pywikibot context) , see https://www.mediawiki.org/wiki/User:KBach-WMF/Collections/Conclusions )