While setting up PageTriage we encountered some bugs which were hard to debug because documentation of the extension's database fields is lacking. Some documentation is provided at https://www.mediawiki.org/wiki/Extension:PageTriage#SQL_tables (and the pages linked there), but it is incomplete.
We should improve this documentation and/or the code-level documentation of these fields, so that new contributors aren't as easily tripped up.
@Novem_Linguae We noticed that you're the primary contributor to these pages. Now that you've been working on the extension for longer (I see most changes were in Nov 2021), do you have capacity to take a pass at updating these pages? It would really help us feel more confident that we understand what's going on.
An alternative option is that we spend some time investigating and updating the pages, but this will obviously take longer.
I think mw:Extension:PageTriage is mostly accurate. I'm pretty good about updating it as I go.
Sounds like you're referring to T333389: make pagetriage_tags.ptrp_tags_updated nullable in database? I'm not sure good documentation would have prevented that. Seems like a developer refactored some code and unintentionally made a not nullable field nullable. That's not exactly documentation related.
You could try regenerating the describe pagetriage_page SQL queries on these pages I suppose: https://www.mediawiki.org/wiki/Extension:PageTriage/pagetriage_page_table etc. Hope that helps.
Sounds like you're referring to T333389: make pagetriage_tags.ptrp_tags_updated nullable in database? I'm not sure good documentation would have prevented that. Seems like a developer refactored some code and unintentionally made a not nullable field nullable. That's not exactly documentation related.
The original issue was not documentation-related, but we found the lack of documentation to be an impediment to identifying and resolving it. Some individual fields have informative documentation at https://www.mediawiki.org/wiki/Extension:PageTriage/pagetriage_page_table or descriptive comments in the code, but not ptrp_tags_updated.
Obviously we were able to figure it out, but there was friction due to the state of the documentation, which is what this task is about. It's our intention to improve the code-level documentation, partly by looking through the code, and partly by reading through the extension page. I actually think this task may be a little too narrowly scoped, as the underlying issue is the need for more complete documentation for properties & parameters, which would cover the database fields.
Questions:
After looking at the feedback in https://en.wikipedia.org/wiki/Wikipedia:Page_Curation/2023_Moderator_Tools_project/Technical_prioritisation I think there's room to discuss how this should rate as a priority, since it's tied to the php documentation.
Are there undocumented things that you're knowledgeable about that you are interested in documenting?
I think I've gotten all the low hanging fruit for now. My workflow is pretty much work on a patch, figure something out about PageTriage, then write about it at mw:Extension:PageTriage. I feel it'd be hard to accelerate that workflow.
Does it make sense to also maintain that info on the extension page, or should we just let code level docs live in code and potentially add the extension to doc.wikimedia.org to have browsable documentation that is always up-to-date?
I find the overview at mw:Extension:PageTriage useful. No objection if you want to improve docblocks though.
What's the acceptance criteria for this task? Does anyone have anything specific in mind, e.g.
make sure every field on the following 3 pages has a heading:
? Or should we mark it as resolved?