Jump to content


About this board

Design process and documentation

Nemo bis (talkcontribs)

Hi. Thanks for what is documented on wiki. Is Design/Team/Process meant to contain also the internal team practices à la Mobile web/Team/Team norms? I'd like to propose two changes, one very simple and the other a bit less.

  1. Design review over specific changes must be provided on the relevant bug or gerrit change (or at the very least public mingle card or whatever). Too often I read on gerrit "Got +1 over [private] email by X, who doesn't use gerrit". Register and publish comments there: very easy. Some team members already do this.
  2. Any design decision broad enough to affect more than one commit (e.g. something for multiple repos, or something that is for now "settled"/"consensual" and should resist for some iterations) must be documented on a mediawiki.org wiki page (note: not talk page), with "state of the art" and rationale/supporting evidence for it. Can be one sentence, or two words per item, a stub is better than nothing.

Undocumented decisions actively disallow anyone outside the inner circle of a team from contributing: this means getting no useful feedback; creating friction; and making design work ineffectual, because design decisions don't self-propagate across the codebase, they need devs to adopt them. Cf. [teampractices] The Rule of Three (+1), [teampractices] [Wmfall] Roles and Processes for WMF Design, [Wikitech-l] Communication of decisions, [Wikitech-l] Meetings vs mailing list, , , (in decreasing order of generality).

I know you're already working on all this (in particular, on the highest priority right now i.e. updating translatable documentation at Typography refresh + FAQs), there's no urgency to reply; but I think that opening this a thread here on wiki will prove useful to document progress in this area over the next few months.

Jaredzimmerman (WMF) (talkcontribs)

Thanks for your comments. While I understand what you're saying with "Design review over specific changes must be provided on the relevant bug or gerrit change" perhaps you could write it as a suggestion rather than a demand, how we say things is often as important as what we say. Second, that is not our process, when we have Design Reviews its mostly for designers to iterate on projects they are currenlty working on, often in-production or pre-production. Individual designers may comment on bugs, but are less likely to do so on gerrit, as it is a tool for developers.

Design reviews rarely result in "decisions," rather they are meant to make the team think critically about their process, and try alternate routes. We always endeavour to make large/important decisions reflective on the project page of anything we work on, but there is a grey area where over documentation can make things muddy and unclear for people trying to understand what a project is about. I feel we do a pretty good job documenting our process, our decisions, and our rational, but like everything in life, there is always room for improvement.

It also seems like your conflating multiple things, our process documentation as a design team (primaries & secondaries, design reviews, etc) with documentation of a feature (typography refresh) while we seek to drive consistency, and build reusable tools and documentation for developers I just want to be clear that those are two totally different things.

Again, thank you for your comments and thoughts.

Reply to "Design process and documentation"
There are no older topics