Talk:Technical Collaboration Guidance/Principles

Jump to navigation Jump to search

Wording and grammar[edit]

I like the idea of such a guideline, and thanks for working on it. Two remarks:

  • responsive is widely understood in programming in a different meaning (it's a UI design that adapts to the device)
  • grammaticaly, the first group of keywords consists of adjectives concerning the product, there is a group of adjectives concerning the developer, and finally a group of nouns. Let's be consistent! I like the first approach the best.

Bináristalk 06:19, 17 November 2015 (UTC)

Thanks for the feedback, I've incorporated both points. Keegan (WMF) (talk) 22:04, 17 November 2015 (UTC)
Responsive was changed to Reactive. Perhaps Adaptive would be nicer? --KSmith (WMF) (talk) 22:58, 17 November 2015 (UTC)
I Like It™. Changing. Keegan (WMF) (talk) 00:51, 18 November 2015 (UTC)
I added a section header, to make it possible in the future to edit just this section. --KSmith (WMF) (talk) 00:04, 20 November 2015 (UTC)
The points are still an odd mix of "Developers should xxx" and "The product should xxx". I would suggest splitting these into 2 separate lists. The first 3 points (and maybe the last one) are about the product. That would also clear up some of the ambiguity (like is is the software that should be adaptive, or the developer?). --KSmith (WMF) (talk) 00:04, 20 November 2015 (UTC)

Scale / Privacy / Security[edit]

I liked how unicef called out Scale and Privacy / Security directly (for obvious, biased reasons). I think these are things are often brought up in code reviews, so to not have them here (except for a minor mention under "Accessible") seems to miss what I think is a "principle" that the developer community holds itself to. But maybe these are meant to embody things we think are missing from the way we currently do things? CSteipp (WMF) (talk) 18:53, 17 November 2015 (UTC)

Yes Done Keegan (WMF) (talk) 22:04, 17 November 2015 (UTC)

+1. Also, can we make the wording take into account that the list isn't exhaustive? --Krenair (talkcontribs) 20:08, 17 November 2015 (UTC)

Sure, I'll poke at the wording there. Keegan (WMF) (talk) 22:04, 17 November 2015 (UTC)
A little semantic detail: maybe what we want to communicate is that the list isn't finished, that is open to suggestions and improvement? When I read that it is not exhaustive my first reaction is "ok, which are the other points?".--Qgil-WMF (talk) 06:55, 9 December 2015 (UTC)


It's good to see this, but I almost want to list "accessible" as a specific item in its own list. It's important to aim for accessibility to people with visual disabilities, for example. Without calling it out specifically, the other meanings might overshadow that one. --KSmith (WMF) (talk) 22:58, 17 November 2015 (UTC)

Good point. The initial idea was to have "accessible" delineate all forms of accessibility, but now that security is split out it might make sense to split this out further. Keegan (WMF) (talk) 00:51, 18 November 2015 (UTC)
@KSmith (WMF): I've changed the wording to "consistent, usable experience for everyone, regardless of user ability." How's that? Keegan (WMF) (talk) 20:26, 18 November 2015 (UTC)
I'm not fond of me that speaks more to a user's "computer literacy" (as we old folks used to say back in the day), and less about physical abilities. I think this point is about tech accessibility (e.g. low bandwidth) and physical accessibility (e.g. blindness) and cognitive ability (e.g. don't make things complicated that could be simple), and perhaps others. --KSmith (WMF) (talk) 00:06, 20 November 2015 (UTC)


"Free" is sadly ambiguous to what it actually means when it comes to software. I would suggest linking to The Free Software Definition by GNU/FSF to explain what we actually mean. Legoktm (talk) 02:42, 18 November 2015 (UTC)

In the homepage we link to w:Free software, and I think this is a better link. --Qgil-WMF (talk) 06:50, 9 December 2015 (UTC)
In fact, what about this:
Be a free knowledge advocate - as a participant in the free software movement, our content and software should always be freely licensed and readily available.

--Qgil-WMF (talk) 07:20, 9 December 2015 (UTC)

is vs should[edit]

In the text there is a combination of "is" and "should" that I find slightly confusing. "is" tends to describe an objective reality, while "should" expresses an aim. "... should always be freely licensed" is consistent with this idea. "... decision making is data-informed" is not consistent with this idea. I wonder if other variants of "should" are missing in "and people driven" and "we provide a consistent".

Collateral comment: "open-source development depends" is imho clearer if we add "our" at the beginning, since other models of open-source development elsewhere might not depend on that factor.--Qgil-WMF (talk) 07:01, 9 December 2015 (UTC)

Connection with Wikimedia Foundation Guiding Principles[edit]

We should probably link to wmf:Resolution:Wikimedia Foundation Guiding Principles and explain the relation between the two documents. If only to assure that readers of these Design and development principles are aware of the Wikimedia Foundation Guiding Principles, also to assure that the intention and wording in both is consistent.--Qgil-WMF (talk) 07:23, 9 December 2015 (UTC)

Iteration and quality[edit]

Good next draft, thank you! - and it's down to 5 items :) I like how this is complied - and I am relieved to see "data-informed" being used in lieu of the dread "data-driven".

I feel like I am missing something around quality and iteration. I think iteration could live in "collaborative and adaptive" - it's already mostly there, but I don't know if the teams when they are followed up with will feel like that is spelled out clearly or if they feel that they develop products iteratively enough that their work is called out in this section.

Re: quality. I think this is also lightly addressed in that same section in "bug reports" - but because the section is "collaborative and adaptive" so I feel like a point around quality gets lost. I'm also not sure if anyone feels the same way and has raised it, but I know for example with bug triage meetings that VE has, it's about listening, but also highly about shipping quality software.

Again, not sure if you are hearing anything else along these lines from the eng/dev/product teams. -Rdicerb (WMF) (talk) 07:59, 9 December 2015 (UTC)

Good point. The stress on quality is spot on. The tension between delivering "good quality" or "on time" (when you cannot choose both) has been contentious, and having an explicit guiding principle would be useful. This is also a point of difference with Wikimedia content, where quality articles or images are not a default requirement for "use in production". Here, the "release soon & often" principle needs to be seen in the context of alpha and beta testing, for full deployments in production, the size and relevance of Wikimedia requires to apply another familiar principle: "It ships when it's ready."--Qgil-WMF (talk) 09:52, 9 December 2015 (UTC)

Better location and links[edit]

This is an important document and currently has a less than ideal URL / page title. Maybe it would be better to have a location closer to WMF product development process? Or at least take Design and development principles. Also, "No pages link to Design and development principles/Principles." The move without redirect might have broken some links. In any case, this page should be more visible.--Qgil-WMF (talk) 22:47, 1 February 2016 (UTC)

Yes Done Now there is a better URL and some pages linking. Thank you!--Qgil-WMF (talk) 09:08, 3 March 2016 (UTC)

What's the last stage of the "product lifecycle"?[edit]

The sentence "Staff and volunteers should be receptive to feedback, feature requests, and bug reports throughout the lifecycle of a product" makes me wonder what's actually the last stage of that "product lifecycle". Receptiveness requires feeling responsible. That might be less of the case when a project is "under maintenance" (no new features added) or even more when its (WMF) development team has been dissolved. --AKlapper (WMF) (talk) 16:26, 14 June 2016 (UTC)

I'd still love to see this answered... Currently th text says "Staff and volunteers should be receptive to feedback, feature requests, and bug reports throughout the lifecycle of a product." and that seems unrealistic without dedicated resource allocation and hence needs rephrasing / differentiation. When a product has reached maturity, companies often move developers to the next thing and call the previous thing "in maintenance mode" - a confusing term creating wrong expectations. My comment touches software development cycles though and hence collides with "TCG explicitly does not focus on the processes of creating software". --AKlapper (WMF) (talk) 13:08, 14 September 2016 (UTC)