Jump to content

Design/Archive/Wikimedia User Interface/User-stories

From mediawiki.org

How would your story help us?

  • A better idea on where to direct our resources to build a UI toolkit that you can and will use
  • Informing how we build a toolkit that fits into your process
  • Understanding what you care about and making sure we address them
  • And generally getting to know how we can work together to bring some consistency with realistic methods around Wikimedia projects.

Share your story

Example questions to answer:

First, give us some context about you

  • Are you a front or back-end engineer? Or neither?
  • What do you care about most when contributing to Wikimedia projects?
  • What is your typical area of contribution in Wikimedia projects?
  • What do you use when improving Wikimedia projects’ pages with better UI components (buttons, menus, etc)
  • Or if you make gadgets / tools that relate to Wikimedia projects, what do you use for UI components? '


Here are some example questions to get started with:

  • How do you go about looking for a UI component? For example, if you need a button, where do you look for it?
  • Have you heard of OOJS UI, what do you think this it's used for?


If you are more of a technical contributor:

  • What’s a framework you most use (even outside of Wikimedia)?
  • Do you read documentation, when do you read documentation?
  • What’s an example of a good framework documentation, what did you appreciate about it and what would you want to know more or less of?
  • What’s an example of a poorly documented documentation, what did you not appreciate about it and what would you want to know more or less of?


Is there anything else you would like to make sure we know when it comes to the UI you build, or the resources you need to do your job when it comes to UI?


Ricordisamoa's story

[edit]

First, give us some context about you

  • Are you a front or back-end engineer? Or neither?
    • Neither.
  • What do you care about most when contributing to Wikimedia projects?
    • Information must be organized efficiently and without redundancy.
  • What is your typical area of contribution in Wikimedia projects?
    • Writing bots, gadgets, user scripts, Lua modules, external tools; notifying communities of software changes affecting them; reporting communities' needs to developers; keeping mailing lists thriving; contributing small patches via Gerrit and GitHub.
  • What do you use when improving Wikimedia projects’ pages with better UI components (buttons, menus, etc)
  • Or if you make gadgets / tools that relate to Wikimedia projects, what do you use for UI components?
    • I try to integrate gadgets and scripts with the existing UI as much as I can. At first I used jQuery UI, as in c:User:Ricordisamoa/ShouldBeSVG.js. Then I discovered OOjs UI, and I'm using it for .


Here are some example questions to get started with:

  • How do you go about looking for a UI component? For example, if you need a button, where do you look for it?
    • When using native HTML elements, I look at MDN; when using a framework, I look at its documentation and existing code.
  • Have you heard of OOJS UI, what do you think this it's used for?
    • I know it's being used more and more for MediaWiki's UI, but I haven't heard of it outside of Wikimedia.


If you are more of a technical contributor:

  • What’s a framework you most use (even outside of Wikimedia)?
  • Do you read documentation, when do you read documentation?
    • I read it frequently, mostly examples.
  • What’s an example of a good framework documentation, what did you appreciate about it and what would you want to know more or less of?
    • Bootstrap is fairly documented: basic examples and many unofficial sites. OOjs UI's documentation is extensive as well, but: this one with static images appears outdated; this one seems to assume some previous knowledge of the framework; live demos are nice but don't show the underlying code. See also phab:T97264#1255071.
  • What’s an example of a poorly documented documentation, what did you not appreciate about it and what would you want to know more or less of?

--Ricordisamoa 23:50, 11 August 2015 (UTC)[reply]

Halfak's story

[edit]

First, give us some context about you

  • Are you a front or back-end engineer? Or neither?
neither
  • What do you care about most when contributing to Wikimedia projects?
That's a really hard question to answer. I guess enabling others is what I'm aiming to do -- through knowledge or a functional UI.
  • What is your typical area of contribution in Wikimedia projects?
I work a lot in the Research namespace on Meta, but I build software products too.
  • What do you use when improving Wikimedia projects’ pages with better UI components (buttons, menus, etc)
Well... I don't usually try to improve a Project Page with a better UI, but when I do, I use templates and lua modules.
  • Or if you make gadgets / tools that relate to Wikimedia projects, what do you use for UI components?
My old stuff was ad-hoc. My more recent stuff uses OOJS ui.


Here are some example questions to get started with:

  • How do you go about looking for a UI component? For example, if you need a button, where do you look for it?
If I already know that I need a button, I just go to the developer reference. https://doc.wikimedia.org/oojs-ui/master/ When I wasn't sure what types of controls were available, I tried working with the living style guide, but it was incomplete. So I used a mix of that and the developer reference.
  • Have you heard of OOJS UI? What do you think this it's used for?
I've been using it. E.g. m:Wiki labels


If you are more of a technical contributor:

  • What’s a framework you most use (even outside of Wikimedia)?
Generally? Man. I dunno. I write a lot of python, so Flask is a common framework that I use. Otherwise, I work a lot in a framework of my own design called revscoring. I still see OOJS UI as a library -- not a framework -- so I think I might not know what you mean to ask here.
  • Do you read documentation? When do you read documentation?
When I'm trying to work out if a library will do what I need it to. I'd also reference it while coding the thing I need.
  • What’s an example of a good framework documentation? What did you appreciate about it and what would you want to know more or less of?
scikit-learn has some really good docs. It's like a developer reference merged with a cookbook. I want just enough cookbook and explanation merged with the developer reference so that I can learn common usage patterns and also dig into the details without switching modes. Flask is an easy example of great docs too.
  • What’s an example of a poor documentation, what did you not appreciate about it and what would you want to know more or less of?
No documentation at all is the worst, of course. pymysql devs seem to expect you to read a reference and make some assumptions about what they implemented. That was pretty lame. Old versions of the living style guide contained code that was *planned* but not in place yet. I spent tens of hours trying to figure out why I thought the library did something that it does not do.

Dan Andreescu

[edit]

I'm both a back-end and front-end engineer, I think those terms are a bit blurred in modern coding. I don't contribute to mediawiki, though I'd love to. I could help with making services out of modular parts of the PHP back end, and I could help make a better more modular UI. I don't because frankly I'm not excited about some of the technical aspects of the project. Tools like Resource Loader are wonderful, but it's hard to love frameworks that aren't used elsewhere and other idiosyncrasies of mediawiki development.

For contrast, here's how I work on UIs these days. I use pre-built basic UI elements, and I prefer Semantic UI over Bootstrap for this. It's easier to understand, have an intuition about, and change. I grab basic UI elements from it and solve problems. When I solve the same problem twice, I make a component. I use Knockout components but I've worked with riot js recently and played with React as well. Any such approach seems fine to me, but I'm more than skeptical of inventing our own with OOJS. When Polymer and Paper become supported on all browsers, I'd love to give those a try, and I think knockout makes the componentization part of my code lightweight and easy to migrate to Web Components when that standard is complete and implemented.

Knockout and Semantic UI are example libraries in my opinion. Their documentation is solid, but beyond that you don't need documentation once you start developing an intuition. You can guess CSS class names and be right most of the time with Semantic. And you can re-use a few basic Knockout principles to build very complicated interactivity. The lack of opinion and the simplicity of these tools is useful to me. I have less experience with Riot JS, and it's a newer library, but it seems to be growing up nicely. All these tools allow me to write less code and get stuff done faster with less complexity and cognitive overhead. I think a good tool should strive for this, because the problems we're solving are complex enough without the tools adding to that.

I think if a project has documentation at all it's usually not terrible to get through. But I particularly dislike Backbone JS's documentation. I find it needlessly confusing and long-winded, and it's explaining a very simple framework. I also dislike the basic approach of frameworks like Angular which try to control every aspect of your code and force you to do things a very specific way. Following that approach has made me paint myself into corners that I've regretted.

Reading, Editing, and Search/Discovery teams (Sept 15, 2015)

[edit]

This is a summarization of a meeting held on 15th of September 2015 with Reading, Editing, and Search/Discovery teams and the UI Standardization team. Original notes from all teams.


UI component library

  • Modularity and completeness as goals will help
  • A component language that designers can share with developers — design should use pieces that dev has available.
  • To easily onboard both engineers and designers with;
  • Serves both prototyping and implementation needs;
  • De-couple HTML / CSS from OOjs UI. It’s easier for engineers and designers to work with CSS classes;
  • Shouldn’t need JS/PHP calls for simple components like button or basic elements - too much overhead for both onboarding and implementation;
  • With Angular directives / custom elements;
  • No vertical team is building things the same way. We should think about performance and standardize to use one library. Concerned about duplication of efforts unnecessarily;
  • Provide standardized styles in prototype environment so it has similar look and feel to what future state looks like so prototypes and production is consistent;
  • Keep MediaWiki UI updated because it’s heavily used on mobile. Or kill it like agreed over a year ago.


Style guide

  • Live examples;
  • How and when to use components;
  • Show use cases / examples to make designing i.e. log in form faster to reduce the amount of decisions;
  • Differentiate CSS and JS;
  • Display each component in four ways - CSS only, JS, PHP, template;
  • Ability to download CSS file / OOjs UI library “npm install oojs-ui”;
  • Align style guide and design at all times so dev and designers have the same version and both sides have the latest available.


Process

  • When design is handed over to dev, implementing a near-perfect mock up should be just a matter of picking and choosing components, not tedious restyling and creation of new components.
  • How to request edits / new icons / new UI / new interaction patterns;
  • How to incorporate / adjust patterns used in different teams / projects;
  • Frequent contact with designers / front-end devs / community;
  • Conversion of more interface to OOjs UI, especially the ones that are easy to achieve.
  • Drive standards around components, but recognize that there are really three standardization problems:
    • style (usually CSS or something that generates CSS)
    • behavior (mix of CSS and JS)
    • generation (how do you bind data to the component, does the template have to know the ins and outs of the HTML or can it abstract from that (see knockout components, or React, or even OOJS for example)



Conversations to have

  • Balance consistency with platform-specific needs. Knowledge of Material Design, iOS guidelines, and web practices.
  • Brown bag on style guides in other companies and orgs


-- MGalloway (WMF) (talk) 18:30, 20 October 2015 (UTC)[reply]

From the Reading Engineering/Design team

[edit]

Here are the results of a request of the WMF reading team to identify blockers to OOjs UI adoption. These are unedited entries made by the individuals on the team who chose to respond to the request for input:

  • Very little internal and external pressure to adopt OOJS despite the deficiencies of $currentFramework (the water is being heated up gradually enough)+1
  • The library is incomplete and we haven't got time to invest the work. Currently no support for matching a route e.g. '#/editor/' with a view.
  • The library is not mobile friendly. For instance OO.ui.Dialog (the equivalent of mobile overlays) is no where near mobile friendly. Having this prioritised would help this.
  • The library seems bloated for mobile users. Mobile in current form only has needs for IconWidget, ButtonWidget, LabelWidget, LookupWidget and Dialog. Having a lighter version available would help this.
  • There is a learning curve for this library, due to the lack of documentation/demos for complex interfaces when compared with established libraries e.g. backbone
  • Time will need to be invested to bring oojs ui designs in line with existing mobile designs.
  • It can be hard to incrementally start using OOjs UI. E.g. a set of buttons in a dialog, any of which advances to the next page: the buttons want to be in a button group, inside your own custom dialog layout subclass (I've got the details wrong). You have to get the whole gestalt before using a single piece is straightforward. VisualEditor shows you how to do this kind of adaptation of OOjs UI, but it's very elaborate sample code.
  • The implementation details need to be well thought out because we don't want to load both OOJS UI and MF code if different features use different libraries.
  • Doesn't match native app UI standards for platforms.
  • JS limits performance and code re-useability in native or semi-native apps
Retrieved from "https://www.mediawiki.org/w/index.php?title=Design/Archive/Wikimedia_User_Interface/User-stories&oldid=6119693"