Talk:Technical Collaboration Guidance

Jump to: navigation, search

About this board

Edit description

Feedback is welcome for the Technical Collaboration Guideline. Not everything may be able to be actioned on immediately, but all contributions are read and considered.

By clicking "Add topic", you agree to our Terms of Use and agree to irrevocably release your text under the CC BY-SA 3.0 License and GFDL

FYI: Volunteer's reflection on technical documentation for Product Team

Halfak (WMF) (talkcontribs)

Might be an interesting case study: Phab:T163069

Reply to "FYI: Volunteer's reflection on technical documentation for Product Team"
MZMcBride (talkcontribs)

There's the subject-space page and then six subpages to read? Can this be consolidated and put on a single page? Each of these seven pages also have separate talk pages. Am I really expected to read 14 pages?

MZMcBride (talkcontribs)

Oh, I found another subpage, Technical Collaboration Guideline/Vision, which of course also has a long talk page. Bleh.

BethNaught (talkcontribs)

I'll copy here what is relevant of a comment I made about how the TCG "handles" community concerns here.

Year after year the WMF has forced out disruptive and controversial software projects. In 2013, it took a community revolt on English Wikipedia for the rollout of VE, which (as I understand it) was ultimately revealed to have been rushed out in part due to financial grant terms, despite it causing significant damage. In 2014 controversy over Flow erupted. It took over a year of kicking and screaming for the WMF to concede that it wouldn't necessarily roll it out globally in the future, and yet more months before it was removed from enwiki, and even then only under threat of a serious flaming at RfC. In 2015 Gather was introduced to enwiki. In this case indeed, actionable blockers were proposed: collections could not be deleted, collections automatically used non-free content in violation of the EDP, the moderation system was very hard to use, and enwiki admins were being expected to patrol it with no benefit to serious contributors of content. Only one of these things was addressed. Complaints continued to be raised about the rest of the problems, but Moushira Elamrawy, the liasion for Gather, instead of understanding and passing on the gravity of these complaints, tried to pacify the community without taking any action about the problems. Eventually an RfC demanded Gather be removed. Then Toby Negrin needed a lot of convincing that yes, we actually meant it, and we wouldn't allow him to kick it into the long grass. Yes, the proposal looked reasonable on the face of it, but all trust had broken down.

For years the WMF has needed to be coerced into listening to community concerns on major software projects. Time after time, staffers have tried to avoid dealing with the issues. Now the TCG says that, to slow down a deployment, the community must declare actionable blockers. It doesn't [explicitly] allow for philosophical differences of opinion. It doesn't mention a community outright rejecting a feature. It's a codification of the existing uphill battle communties face when trying to get their fundamental, deep concerns heard about a project in progress.

Keegan (WMF) (talkcontribs)

Hi BethNaught,

I understand where you are coming from, and perhaps I can explain the difference here in implementation with the TCG and the previous experiences. Please keep in mind I might speak in some broad generalities in a few cases, and know that I understand specifics are much more complicated.

When the previous instances have occurred, a good deal of the pain and division was created by miscommunications, a lack of clarity in expectations, and a lack of clarity in roles and responsibilities in developing and deploying software. These failures create the philosophical differences that end up often times dividing and inflaming releases. Identification and engagement with communities and community members should be taking place from the inception of an idea, with discussions along the way as needed to review and mold the product to make sure that it fits community needs, both in philosophy and hands-on work.

What we often had in the past occurrences was a lack of engagement from the start of the idea; the result was that the WMF had the idea, built out the prototype or whatnot, released it, then asked for feedback. At that point we're in the bad feedback loop cycle, from the very start. At this point is when, as you say, the "philosophical differences of opinion" come to head and there's really no fruitful outcome to be had for anyone, because we weren't all on the same page from the start.

The idea behind the TCG is that communities and community members should be on the same page from the start. Ideas can be discussed through to make sure these philosophical differences are worked out before it is too late, identifying what a product can and can't do to fulfil the needs of the communities. In light of this approach, I do not consider it a codification of the uphill battle. If the idea was to continue on in the "old way," so-to-speak, just dropping things on communities and not taking "I don't like it" for an answer, I'd be much more inclined to agree with you.

Now, with that said, "I don't like it" still isn't a valid answer for blocking software, just as it's not a reason for changing content or policies on the wikis. What should occur is collaboration and consensus building, and we at the WMF can work on doing that from the start, just as volunteers do to build the projects.

BethNaught (talkcontribs)

Thank you for your considered and thoughtful answer which clarifies a few points. I would say that "I like it" isn't a reason for mandating a software deployment either. When there is agreement about a fundamental idea, the TCG seems to me to be a collation of good practice which ought to be observed. It might have helped the PageTriage extension and the abortive page creation workflow on enwiki, for example. Also, if as you say, collaboration on ideas from the start means that certain disliked ideas will be more readily killed off, that is good.

One specific provision I question in light of your comment is "It may happen that one or just a few communities will keep pushing back a new product/feature while all the rest are happy with it. The likely scenarios are that either the new product/feature keeps spreading until reaching full coverage, or the community concerns grow and ultimately force a change of product plans" (from /Community decisions). This needs to be better defined. Last time I heard, the Related Pages extension is not being deployed on dewiki because of their Themenring policy, although some other wikis actively welcome it. This is a counterexample. While I realise having many wikis with different combinations of extensions can be a pain, the TCG needs to lay out under what circumstances individual wiki opt-outs are possible/likely. "Change of product plans" is unhelpfully vague IMO.

Keegan (WMF) (talkcontribs)

I agree about your points that need better defined - and I'd extend that to most points raised in the TCG as a whole. This is something I think about constantly, and is something that will be pursued in the future. The idea right now is to establish some baselines and best practices in communication, which in turn will lead to general good habits around discussing ideas, transparency both in planning and decision making, and all those other dreams of working better, together. There's a whole lot of steps in between to accomplish this, and it will take a lot of time, but that's the general vision here.

tl;dr, in response to your further points, is they are good ones. We have to discuss and detail opt-in/opt-out criteria. That is a large topic on its own right, and will have to be worked out as a separate project from the TCG. It will happen, though I have not discussed any timeframes for those conversations at this point. Getting down these baselines of communications is a first step.

Summary by Keegan (WMF)


GDubuc (WMF) (talkcontribs)

I would like to suggest adding performance to the same level of requirement as privacy and security. When any of those considerations are explored after the fact, it can be expensive, or completely impractical in the most extreme cases, to apply. It can be a legitimate blocker for a launch when something is slow, just as it is when it's insecure or has privacy issues.

A slow service is also a service inaccessible in many parts of the world, as people tend to give up before a slow feature loads. In that sense it's a sub-part of the accessibility criteria already listed here.

Keegan (WMF) (talkcontribs)

Good point, thank you. I'll look into it for the next draft.

MZMcBride (talkcontribs)

After being reminded of phabricator:T130470, I think we should make sure any document of this nature includes guidance about documenting lessons learned from failed projects and deployments. To not summarize and document past failings (and successes!) is to waste both donor time and money in an unacceptable way, in my opinion.

As noted in a separate thread, I haven't read everything written here, so this may already be covered in this guideline.

Keegan (WMF) (talkcontribs)

Postmortems are not currently in the TCG, but it's a good idea to look at working something in about them. Thanks for that.

Keegan (WMF) (talkcontribs)

I've received a good deal of feedback about the TCG being called a "guideline," since the word guideline has a specific connotation - it's a form of instruction. This was giving a false impression of the TCG, where we wanted the emphasis to be on the guidance provided. As such, I changed the name.

Explicit mention of Beta Features

Summary by Keegan (WMF)

Added Beta Features info and links into "Where" in Milestone Communication.

Qgil-WMF (talkcontribs)

I just noticed that there are no explicit mentions to Beta Features, and I think a mention and a link would be useful for those not aware or familiar with this process. Even a link to Beta Features/Package might be informative to those curious about how this process works.

Whatamidoing (WMF) (talkcontribs)

I agree. Not all projects can be run through Beta Features, but it's worth including a link.

Timing for TCG draft review with product teams

JMatazzoni (WMF) (talkcontribs)

I see that in Q2 we were meant to "Thoroughly review the TCG draft with ...product teams." I'm pretty sure that didn't happen yet (though the quarter has ended).

However, I've just proposed that we discuss the TCG draft at our next All Product meeting, Feb. 7, so I think you might consider it reviewed shortly after that. Maybe a week or two?

Keegan (WMF) (talkcontribs)

Right, the review is not complete (and the task for the review is still open). Thanks for setting that up; my position on the timeframes has always been much more about meeting the objective than the end date.

Reply to "Timing for TCG draft review with product teams"
DannyH (WMF) (talkcontribs)

Keegan: Reading the current draft, I think you might be over-confident about getting things translated.

In Technical Collaboration Guideline/Translation, you say that there's two steps -- getting translations and distributing translations. I think that first step is actually two steps -- marking a wiki page for translation, and then getting people to translate it. Marking a page for translation is a tricky process to learn, and if I remember it correctly, you need a special user right to do it.

Once a page is marked for translation, things get a bit tricky -- updating the page means that messages need to be re-translated, but it's a judgment call about when the change is significant enough to ask people to re-translate. You also run the risk of burning out the volunteer translators.

So I think the guideline on Technical Collaboration Guideline/Milestone communication might need some more nuance. :) Right now, it says "translations must be had if an announcement is being made that concerns projects in languages other than just English." That's a very broad guideline that potentially puts a great deal of work on the translators' to-do list. Can we make that more specific, or offer a best practice like "once a month/quarter, you should have at least one announcement/update that's marked for translation"?

In general, I'm very happy to see the emphasis on early communication and openness with the community -- more on-wiki discussion, publishing early wireframes, etc. It's hard for product managers and designers to get used to that -- in most other settings, you don't show people your ideas until you've polished them up a bit. So more guidance/expectations-setting/support for that will help a lot.

Keegan (WMF) (talkcontribs)

Great feedback on the Translations, very helpful. I'm stuck on that page and this helps me think it through.

Rogol Domedonfors (talkcontribs)

I think there's another good point here about it being hard for managers and designers to get used to the early exposure of their ideas. It would be easy to just brush it aside saying, well Wikimedia projects aren't "most other settings" but I think we can go a little deeper. The content contributors work like that all the time. Content is published and immediately exposed to scrutiny, review, criticism and so on. So the content contributor community are used to that and not going to be sympathetic to the notion that designers wouldn't want to work like that. It is also true that content criticism is widely felt to be somewhat draconian, and that might explain why interactions between that community and the designers and coders can get rather bumpy. However, what we need to do is manage that interaction into productive channels, not shy away from it. It really is important that we get this right and make it a productive and stimulating, if not always comfortable process.

DannyH (WMF) (talkcontribs)

Yes, I agree. This takes product managers and designers out of our comfort zone, but I think it's important to do that. We need to be more comfortable publishing early ideas and sketches.

Keegan (WMF) (talkcontribs)

Thanks, you two, and more importantly thanks for bringing up one of the underlying issues. It gets me thinking about how we can turn this into something in the future. Much appreciated.

Rogol Domedonfors (talkcontribs)

Just to follow up on that, I would suggest that most projects would or should be co-created with the community of users. The notion that developers evolve ideas for new products or functionalities in isolation from the needs and wishes of the community, then deliver them fully formed to a grateful but essentially passive public I think only needs to be articulated to be discredited. And yet this is how some of the major rows between the Foundation and the Community have arisen.

Whatamidoing (WMF) (talkcontribs)

I disagree with this idea that the devs – most of whom are volunteer devs, just like most Wikipedia editors are volunteer editors – aren't part of "the community of users". If you meant this only to refer to those devs paid by the WMF at the moment, then I'll point out again that some staff devs are admins on the projects and make thousands of content contributions each year. Over the years, about half of the WMF's staff and more than half of the (volunteer and staff) devs have come straight out of "the community of users".

But even if you define paid devs as no longer being users, in reality, if you're an admin at Commons in your volunteer capacity, and you're working on Multimedia in your staff capacity, then your software project is never going to be developed "in isolation from the needs and wishes of the community". It is not at all unusual for product teams to have devs with advanced user rights and to be intimately familiar with at least one of the affected communities. VisualEditor and Collaboration have several Wikipedia admins; Multimedia and Parsing have at least two at the moment; Language's PM is a volunteer admin at seven different public projects. The dev teams often look first to the communities when they have a job opening, and the result is that many devs are community first, and staff second.

Rogol Domedonfors (talkcontribs)

I do not believe that a developer also being a user means that there is no necessity for engage with consult the wider community when formulating requirements, designing software or planning project. Ido not accept that it is unnecessary for a developer to look further than their own personal experience or inclinations when starting up new ideas. It is clear that while some, even many, developers may also be users, the vast majority of users are not developers, and so their views, wishes and needs are not represented by this navel-gazing approach to software design. If you think that the overlap between developers and users is in itself sufficient to eliminate the need for any further effort to engage users in co-creating software then you must have been sadly disillusioned by such projects as Media Viewer / Superprotect, Gather and Knowledge Engine. It is clear that users and developers are different roles, and while enacting those roles people have different views, adopt different attitudes and take different sorts of action. The communities are distinct, with different venues, discussions modealities and cultures. Rather than pretending all is well (since it obviously is not), it is better to articulate those differences and explicitly address them, evolving proecesses that can be used to co-create effectively and productively

Rogol Domedonfors (talkcontribs)

On the translation issue, I can see that there is a load here. Is it possible to lighten that load by technical means? We are not talking about formal translation processes for stable documentation that needs and deserves high-quality translation for a product of long-term value to all language communities, but a "good enough" tool that can give a reasonably accurate rendering into some subset of the major working languages in close to real time for the purpose of discussion and planning. This would be of quite wide application here and at Meta, I would have thought.

Qgil-WMF (talkcontribs)

On translation load and quality of translations, note that translation engines may be used in, currently with the Apertium engine enabled. Just like volunteer editors and translators are driving the use of this tool and translation engines in other wikis, they could also do it here.

Once a ok-ish translation is available in a language, it is easy for the readers of that language to polish it if there is enough interest -- a factor that relates to the relevance or popularity of a specific announcement.

LPfi (talkcontribs)

I do not know how well machine translation works between "major working languages", but last I checked, translation for e.g. Swedish, and especially Finnish, was mainly a joke (you may get an idea of what is discussed, but you won't know what view is supported). If trying to "polish", the language usually stays ugly, and important errors may pass unnoticed. Translating from scratch gives better results, often with less effort. I suppose Arabic and Chinese are as hard as Finnish to get right, if translating from English.

Qgil-WMF (talkcontribs)

As a native Catalan speaker I understand very well the challenges of most languages versus automatic translation engines. Still, the overall picture is not as bad if we add translation memory to the mix, another feature supported by our translation tools and available in

The first time that i.e. "Try out this new beta feature!" is posted in a translatable announcement, translation engines will help some languages more than other, and manual translation will help nurturing the memory in all languages translated. The second time that sentence is used in another announcement, all that memory will be available in the languages that were translated to once, and volunteers will just need to click once to get the translation offered.

This means that a new recommendation is emerging: write announcements in a structured, modular way, recycling as many components as possible. This might sound boring and mechanic to some, but actually makes it a lot easier to get an announcement translated to many languages and therefore reaching more and more diverse users.

I also bet that native English speakers would welcome a more concise, structured and predictable approach to tech announcements, even if it comes at the expense of some individual style and creativity.

Whatamidoing (WMF) (talkcontribs)

Getting translations for brief announcements isn't usually difficult. But translations for whole pages is less likely to happen, and getting timely updates is particularly unlikely. There are many VisualEditor pages that were translated in mid-2013 and haven't been touched since then.

Using structured data (=an infobox) helps, because you can translate the template once and get some automatic updates. It's also helpful to write a basic introduction or a {{nutshell}}-like summary for the project in Simple English, and to request translations for that.

However, using Extension:Translate to mark up a page is going to discourage people from updating the page. It moves the documentation from "the product page that anyone can edit" to "the product page that almost nobody can edit, and nobody does".

Rogol Domedonfors (talkcontribs)

Hence my suggestion for a technical solution that would at least alleviate some of the burden.

Qgil-WMF (talkcontribs)

All this calls for a reasonably consistent approach to project documentation and updates, which is a good thing in itself, regardless of translations.

How should the regular documentation of a project look like? This is how I see it.

  • Project information page. Acts as landing page, provides basic information for all audiences and links to the rest. Translatable. It has an infobox and default structure of sections to be defined. The emphasis on translations is put in the infobox & first section, which should contain the most basic information and links to updates. All the rest is nice to have.
  • Milestone subpages. The TCG recommends to communicate around milestones. There would be a list of recommended milestones: project idea, beta...) and each of these milestones would have its own page for modular documentation and focused discussion. These pages would be in English, feedback in other languages in their discussion pages would be accepted.
  • The announcements about new milestone / milestone completed would be open for translation. Here is where the focus on structured language may make life for translators a lot easier. Imagine i.e. a template for a Design Review announcement, where the moving pieces are the project name, the short description (translated already in the project info page), the URL of the review, and the specific dates of the timeline.
  • User Help pages, which already have a translation process.
  • Developer documentation pages, which is OK to have in English only.

With such structure, translations would be focusing on

  • Project intro and infobox
  • Milestone announcements, based on templates.

The rest would be based on the translators' interest in translating further, but would not be as critical in terms of missing basic information and updates.

Keegan (WMF) (talkcontribs)

Great discussion, all. It sounds like when I re-write the translation page, there are some issues and opportunities to outline with our translations processes. Examples include: while accepting machine translations, keep in mind that they probably need a human eye at some point (though, aside from recruitment, that's out of one's control in a volunteer environment), the longer a message gets, the harder it is to have translated, burnout, to name a few. I can take many of these points to a higher level after I think about it a bit.

Thank you all, more comments in this or any other/new section are always appreciated.

Reply to "Translation load"
Vojtěch Dostál (talkcontribs)

I just wanna say thanks for drafting this guideline. I think it is important for all of us to follow the rules which are outlined in it.

I especially support clear communication of roadmaps - i.e. when the thing will be finished, deployed etc. And if the plan is delayed, the delay needs to be communicated too.

Risker (talkcontribs)

I too want to extend my thanks. One thought that has occurred to me is that, despite the number of software enhancements that have been developed over the last few years to encourage users to be supportive and/or to recognize contributions (e.g., the "thank" buttons), the "tech" community itself hasn't really "walked the talk". This is a step in a very good direction. There are lots of opportunities for outreach to both broad and narrow communities to recruit people as testers, feedback providers and early adopters of "experimental" software.

Reply to "Thank you"