Qgil created this task. Qgil added a subscriber: Qgil. Qgil added projects: Project-Creators, dev.wikimedia.org, Engineering-Community, MediaWiki-Documentation, Pywikibot-documentation.
TASK DESCRIPTION * Project name: Documentation * Description: A tag to identify tasks requiring technical documentation. See also [[ https://www.mediawiki.org/wiki/Documentation | mw:Documentation ]]. * Type: Tag * Policy: Default
The tracking bug {T2001} has been the way to collect bugs related with technical documentation. Now that a technical writer is about to join the #Engineering-Community team (T565), it is a good time to add a bit more of sophistication for better planning.
Note also that #mediawiki-documentation and #pywikibot-documentation (a tag?) exist as well.
Then there is #dev.wikimedia.org, but this is a documentation project on its own.
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Qgil Cc: Aklapper, Qgil, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Spage added a subscriber: Spage. Spage added a comment.
A lightweight `doc-needed` tag is the BZ approach. @Aklapper do you think this is redundant when we have the `MediaWiki-Documentation` project? Mozilla https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Getting_documentation_updated replaces their BZ tag with a `doc-completed` tag so lagging documentation doesn't stop a task from being resolved; I dunno if a `MediaWiki-Documentation-resolved` project or tag would make sense
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Spage Cc: Aklapper, Qgil, Spage, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper claimed this task.
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper added a comment.
Description says "//technical// documentation". Would e.g. Task 64446 still be "technical documentation" or already user docs (if something like that exists)? Is a license file still documentation (Task 67270, I think not)? What is non-technical documentation? (Developer vs end user docs? API docs vs some on-wiki docs? Phun phun phun! Probably we do not want to discuss this here; it's bikesheddy.)
- Create a #documentation tag: Sounds good to me if commonly considered an umbrella tag. - Then kill https://phabricator.wikimedia.org/T2001 by adding that new tag to all tickets: Yes! Also see https://phabricator.wikimedia.org/T75703. - I propose creating a Herald rule to automatically add the #documentation tag to tasks that have the projects https://phabricator.wikimedia.org/tag/mediawiki-documentation/ and https://phabricator.wikimedia.org/tag/pywikibot-documentation/ set (like for VE, see https://phabricator.wikimedia.org/T76954). - Manually add the new tag to open tickets under these previously existing projects. More complete search results for the win. - Keep https://phabricator.wikimedia.org/tag/mediawiki-documentation/ as is for the time being. Long version: It has 25 open tasks https://phabricator.wikimedia.org/maniphest/query/lWQYGbOJ6C0m/#R. Initially I thought I'd like to kill that component but some stuff really is in MW Core's specific /doc area which I consider a "partial codebase that can be defined" (my very personal definition of a project). Might kill and move to generic project once the slighly derailed discussion in https://phabricator.wikimedia.org/T76942 has ended in $something-actionable. - Unrelated: Want to kill https://phabricator.wikimedia.org/T66840 too in favor of https://phabricator.wikimedia.org/tag/pywikibot-documentation/. I've commented there. (Another messy fragmentation example thanks to Bugzilla's tracking bugs, keywords, components. There are many such examples.)
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper added a comment.
@Spage: Let me try to understand your workflow needs by asking ignorant questions and adding high-level rants. <tl;dr>: I'm not convinced how Mozilla handles it in BZ is good. I cannot offer a great idea either though.
In https://phabricator.wikimedia.org/T85485#948235, @Spage wrote:
A lightweight `doc-needed` tag is the BZ approach. @Aklapper do you think this is redundant when we have the `MediaWiki-Documentation` project?
I wonder what is the differentiation... An open Phabricator task that has a documentation project/tag is where some doc update or doc creation is needed. If creation of dedicated doc tasks for "we still needs docs for the code we fixed in task xyz" has ever happened in the past, then only sporadically.
Mozilla https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Getting_documentation_updated replaces their BZ tag with a `doc-completed` tag so lagging documentation doesn't stop a task from being resolved
Having some BZ keyword is probably still better than a TODO comment in the code or nothing at all //if you don't want to create a separate task about the documentation part// of a code change. Advantage: Separate tasks have their own status that can be open or resolved. Disadvantage: Takes way longer to create that separate task about the docs than just adding a tag/keyword or a dedicated field (like RedHat Bugzilla does to integrate their "devs work on task, then docs and qa work on followup stuff for that task"). Most important: People are lazy.
I don't get the "remove doc-needed and add doc-completed" part though. I consider any Bugzilla keywords ⩯ Phabricator projects/tags which have some semantic relation between each other (tag Y should be set after tag X) and try to reflect some parallel status system fundamentally busted and error-prone as those semantics cannot be technically expressed. That would have been a usecase for a flag dropdown in BZ which we don't have that in Phab.
In more actionable words: Why is the "doc-completed" part needed? Does someone really want to query which docs have been fixed //specifically// for code changes of developers who did not update/provide the docs themselves? Is such differentiation really wanted, or could you also just remove the "doc-needed" keyword, once docs have been fixed?
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper added a comment.
Spontaneous thought after adding my last comment: If a "dev closes code task as fixed, now either docs and/or qa should do their work" workflow exists I'd personally prefer separate followup tasks. As creation is cumbersone, having some custom "create followup task for docs team" one-click button prefiling all values would be nice... or such. Wondering if there are other thoughts.
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Qgil added a project: Team-Practices. Qgil added a comment.
OK to @aklapper's comments in https://phabricator.wikimedia.org/T85485#950876 (skipping the bike-shedding part). :)
On the process side, I personally think that if a task has a code part and a documentation part, the task cannot be closed until the documentation part is closed. This is how developers don't //forget// about documenting in the first place. But this is more a https://phabricator.wikimedia.org/tag/team-practices/ topic than something that should be decided in this task.
It seems that we have enough consensus to create the #Documentation tag, right?
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper, Qgil Cc: Aklapper, Qgil, Spage, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
jayvdb added a subscriber: jayvdb.
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper, jayvdb Cc: Aklapper, Qgil, Spage, jayvdb, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper added a project: documentation.
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, jayvdb, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper added a comment.
- https://phabricator.wikimedia.org/tag/documentation/ project created. - Open tasks under https://phabricator.wikimedia.org/tag/mediawiki-documentation/ were added to this project. - Open tasks under https://phabricator.wikimedia.org/tag/pywikibot-documentation/ were added to this project. - https://phabricator.wikimedia.org/herald/rule/11/ created to always add https://phabricator.wikimedia.org/tag/documentation/ when a task has one of those two projects associated. - (Rather unrelated: https://phabricator.wikimedia.org/T66840 got closed.)
Rest will follow another day:
- Close https://phabricator.wikimedia.org/T2001 after mass-adding the https://phabricator.wikimedia.org/tag/documentation/ project to the tickets blocking 2007 https://phabricator.wikimedia.org/maniphest/query/YvonueWwIkc9/#R.
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, jayvdb, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper raised the priority of this task from "Normal" to "High".
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, jayvdb, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Awjrichards added a subscriber: Awjrichards. Awjrichards added a comment.
@Aklapper, @qgil are there any specific asks of the Team Practices Group here, or did you just want to keep this on our radar?
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper, Awjrichards Cc: Aklapper, Qgil, Spage, jayvdb, Awjrichards, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper added a comment.
@Awjrichards: Basically how "this task has been fixed when it comes to code and the behavior is now as expected, but the documentation part still needs to be done" should be preferably handled.
- Do not close the task until documentation has been added/updated (and potentially change assignee)? - Close task and create followup task for adding/updating documentation? - Some other workflow that might work better?
And: Is this actually a common problem that deserves more thoughts and discussion between S and Team-Practices?
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, jayvdb, Awjrichards, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Aklapper closed this task as "Resolved". Aklapper added a comment.
All done (tasks tagged and closed https://phabricator.wikimedia.org/T2001).
For the workflow related aspect we can either continue discussing here or in a dedicated ticket.
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper Cc: Aklapper, Qgil, Spage, jayvdb, Awjrichards, Gryllida, Jdforrester-WMF, Rfarrand, pywikipedia-bugs
Awjrichards moved this task to Done on the Team-Practices workboard.
TASK DETAIL https://phabricator.wikimedia.org/T85485
WORKBOARD https://phabricator.wikimedia.org/project/board/56/
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper, Awjrichards Cc: jayvdb, Qgil, Awjrichards, Aklapper, Spage, Gryllida, Parent5446, Jdforrester-WMF, Rfarrand, Ltrlg, Krenair, pywikipedia-bugs
Awjrichards edited projects, added Team-Practices-This-Week; removed Team-Practices.
TASK DETAIL https://phabricator.wikimedia.org/T85485
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper, Awjrichards Cc: jayvdb, Qgil, Awjrichards, Aklapper, Spage, Gryllida, Parent5446, Jdforrester-WMF, Rfarrand, Ltrlg, Krenair, pywikipedia-bugs
Awjrichards moved this task to Done on the Team-Practices-This-Week workboard.
TASK DETAIL https://phabricator.wikimedia.org/T85485
WORKBOARD https://phabricator.wikimedia.org/project/board/1105/
REPLY HANDLER ACTIONS Reply to comment or attach files, or !close, !claim, !unsubscribe or !assign <username>.
EMAIL PREFERENCES https://phabricator.wikimedia.org/settings/panel/emailpreferences/
To: Aklapper, Awjrichards Cc: jayvdb, Qgil, Awjrichards, Aklapper, Spage, Gryllida, Parent5446, Jdforrester-WMF, Rfarrand, Ltrlg, Krenair, pywikipedia-bugs
pywikipedia-bugs@lists.wikimedia.org