GeezerVison

This page is outdated. This page contains historical design documentation. See Design or the UI-Standardization workboard for resources and up-to-date information. If you have checked or updated this page and found the content to be suitable, please remove this notice. See the talk page for a possible discussion on this.

This document described the process of design review to be used on user-facing projects for the Wikimedia Foundation.

"A day spent in planning is worth two days in production."

Design review - especially public design review - should be considered an essential part of any project's lifecycle. Early, iterative design review with multiple parties can prevent most, if not all, production-era difficulties.

Good documentation and the process surrounding it allows a development team to react quickly to any problems that arise. Designing through documentation allows the development team to realize problems before coding and account for them at that point - before the point of no return.

Without a proper documentation process, features are nearly always built twice or three times: the initial build, the secondary build when you know what you're building, and the third build to bug fix the second build. Properly designed, features require only 1.5 "builds": once in documentation, and a half time in implementation.

The goal of documentation and review is to decrease development time, not to increase.

The process of "designing by code" should be discouraged heavily for the following reasons:

1. Development teams should be able and willing to throw away the design at any point in time if the design becomes untenable. This strength is removed when designing via code or prototype: developers are generally unwilling to discard work as useless. Designing through documentation obviates this weakness.
2. Designing through code locks the development team into a cycle of ever-decreasing options. Once code has been written, further refinement of the design is informed by existing code... which is then informs the next iteration of thought.
3. Design through code limits design input to code developers. It is difficult for non-coders to provide meaningful and timely criticism when doing so requires a skillset they may not have. Everyone can type and leave comments on a document; commit access is limited.

The structure of a WMF project design document can vary depending on project purpose and origin. However, in general, a WMF project design document should include the following:

1. Abstract - This section of the document answers questions about the project. What is the project? What is its purpose? What are the requirements?
2. Rationale - This section explains the value of the project, why we think it is of value, and how it fits into the bigger picture.
3. Process - Often cut into multiple sections, this describes how the feature is intended to work.
4. Gallery and Assets - These are images that are essential to understand the project. Mockups, screenshots, and icons fall into this category.

Please place your design document on a public wiki page on mediawiki.org (such as a section or subpage of your Extension: page) and let the Wikimedia Foundation design team know about it, by emailing their mailing list and/or leaving a talk page message for Senior Designer Brandon Harris.

Screenshots and mockups within a WMF design document must be of "high fidelity".

There are multiple camps concerning the degree of fidelity kept within design documents. If the audience of the WMF's design documents were small and internal, simple wireframes would likely suffice. However, the WMF project communities are not trained to think like developers and can be confused by abstractions. For this reason, mockups should be done in the highest fidelity possible.

The process for public reviewing WMF project design documents is as follows:

1. The designer writes the design document and publishes it to mediawiki.org
2. The designer sends out a "request for review" mail to the wikitech-l mailing list
3. The designer posts the document link into the #mediawiki IRC channel for review and discussion
4. If need be, the designer creates a new discussion thread on the appropriate Village Pump for the feature (typically the "technical" pump on enwiki). This step may often be omitted.

At least a week shall be allowed for comments from the public to be made, addressed, and iterated upon.

After the public design has been posted (but not necessarily after the week has ended), an internal, Foundation-staff design review round-table shall be held. This is a physical meeting that anyone may attend. The design is to be presented and then critiqued.

This meeting should be a "no laptops" meeting with a couple exceptions (the presenter and a note-taker). It should be run informally but not allowed to digress into "rat holes".

The designer should then update the design based on feedback and send out notification when the design has been updated. Additional meetings are not required unless the design changes significantly; email acceptance should be viable at this point.

If further iterations on the design are required, the process shall repeat.

Acceptance criteria for designs are often difficult to establish. Ideally, a design document will include acceptance criteria that must be met (typically the project requirements). However, given the community-oriented nature of WMF projects, this may not be easily obtainable.

Common sense that consensus has been reached should be taken into account.

• Outdated pages