Page MenuHomePhabricator

Create Documentation tag
Closed, ResolvedPublic


  • Project name: Documentation
  • Description: A tag to identify tasks requiring technical documentation. See also mw:Documentation.
  • Type: Tag
  • Policy: Default

The tracking bug T2001: [DO NOT USE] Documentation is out of date, incomplete (tracking) [superseded by #Documentation] has been the way to collect bugs related with technical documentation. Now that a technical writer is about to join the Developer-Advocacy 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, but this is a documentation project on its own.

Event Timeline

Qgil raised the priority of this task from to Medium.
Qgil updated the task description. (Show Details)
Qgil added a subscriber: Qgil.

A lightweight doc-needed tag is the BZ approach. @Aklapper do you think this is redundant when we have the MediaWiki-Documentation project? Mozilla 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

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 T2001 by adding that new tag to all tickets: Yes! Also see T75703.
  • I propose creating a Herald rule to automatically add the Documentation tag to tasks that have the projects MediaWiki-Documentation and Pywikibot-Documentation set (like for VE, see T76954).
  • Manually add the new tag to open tickets under these previously existing projects. More complete search results for the win.
  • Keep MediaWiki-Documentation as is for the time being. Long version: It has 25 open tasks. 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 T76942 has ended in $something-actionable.
  • Unrelated: Want to kill T66840 too in favor of Pywikibot-Documentation. I've commented there. (Another messy fragmentation example thanks to Bugzilla's tracking bugs, keywords, components. There are many such examples.)

@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.

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 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?

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.

OK to @Aklapper's comments in 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 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?

Rest will follow another day:

Aklapper raised the priority of this task from Medium to High.Jan 5 2015, 1:18 PM

@Aklapper, @Qgil are there any specific asks of the Team Practices Group here, or did you just want to keep this on our radar?

@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?

All done (tasks tagged and closed T2001).

For the workflow related aspect we can either continue discussing here or in a dedicated ticket.