Thank you @Harej. Since we can assign one task to one column/category only, what do you prefer for this one, documentation or APIs?

Documentation please.

Highly seconding this. For example when someone wants to make a dialog box in OOjs UI:

function MyDialog( config ) {
  MyDialog.super.call( this, config );
}
OO.inheritClass( MyDialog, OO.ui.Dialog ); 
MyDialog.static.title = 'Simple dialog';

MyDialog.prototype.initialize = function () {
  MyDialog.super.prototype.initialize.call( this );
  this.content = new OO.ui.PanelLayout( { padded: true, expanded: false } );
  this.content.$element.append( '<p>A simple dialog window. Press \'Esc\' to close. </p>' );
  this.$body.append( this.content.$element );
};
MyDialog.prototype.getBodyHeight = function () {
  return this.content.$element.outerHeight( true );
};
var myDialog = new MyDialog( {
  size: 'medium'
} ); 
var windowManager = new OO.ui.WindowManager();
$( 'body' ).append( windowManager.$element );
windowManager.addWindows( [ myDialog ] );
windowManager.openWindow( myDialog );

(Copied from here). But a jquery ui dialog is like this:

$( function() {
   $( "#dialog" ).dialog();
 } );

(From jquery ui doc.)

What I would love to see is some sort of form factory in javascript. Like HTMLFormFactory in php. So we only build an array of form descriptors and call it, then bam! the form is there.

I'd like to add gadget developers to the scope of this task. For some tasks I'd like to have a gadget/user JavaScript that takes a string or some other values from the user in a dialog box and does something with them. I'm pretty sure that can be done with OOjs UI, but it seems to be way too complicated for someone who wants to invest maybe half an hour.

I agree that gadget developers would also benefit.

In PHP if you are extending the FormSpecialPage class you can define an array (a JSON blob basically, but PHP) for your form and then the form is generated based on the data you supply. This should be made available in the JavaScript components if it is not already.

In T155473#2944504, @Ladsgroup wrote:

What I would love to see is some sort of form factory in javascript. Like HTMLFormFactory in php. So we only build an array of form descriptors and call it, then bam! the form is there.

YES.

I think there are two separate wishes here. One is incremental improvements to OOUI (mainly high-level documentation and a better maintained liing style guide, I guess) without any major changes to what it is. The second is to refocus on higher-level use cases (or possibly create a wrapper library that hides all the boilerplate) - OOUI was originally written for VisualEditor, and as a result it is a very flexible low-level tool (I doubt you could write a WYSIWYG GUI in Semantic UI) but relatively cumbersome to use, while jQuery UI and co focus on a few common high-level use cases such as forms, dialogs, and tabs and other common navigation tools.

@Tgr, I clarified the task to be solely about documentation.

@Volker_E and I talked about OOjs UI documentation (and lack thereof for key areas) with a few people who are planning or starting to use OOjs UI in their projects (in particular, @Jonas for Wikidata/VisualEditor integration, and @santhosh for ContentTranslation). And @Isarra has been regularly bugging me about OOjs UI in CollaborationHub. It's really something we want to improve.

It would be helpful to have a list of poorly documented (or not at all documented) areas. Sometimes things are obvious to me, since I've been working with the library (and on it) for a pretty long while now, and I don't even see they're not documented. From what I recall, @santhosh mentioned poor docs for the event system and subclassing (I have an email listing specifics in my inbox somewhere), and @Jonas was wishing for a "landing page" like http://wikiba.se/ (T85466). But I'll forget these things if you don't write them down :D

We should also probably go through all the big changes since early 2015 (when the bulk of https://www.mediawiki.org/wiki/OOjs_UI was written by @KMenger, she was contracted specifically to work on that, and I think the parts that we did document were documented quite well), particularly the breaking ones, and make sure that documentation is up to date. We definitely documented some of them, but definitely not all.

I made T155567: Make OOUI easier to use for gadgets as a separate wish.

In T155473#2947081, @matmarex wrote:

It would be helpful to have a list of poorly documented (or not at all documented) areas. Sometimes things are obvious to me, since I've been working with the library (and on it) for a pretty long while now, and I don't even see they're not documented. From what I recall, @santhosh mentioned poor docs for the event system and subclassing (I have an email listing specifics in my inbox somewhere), and @Jonas was wishing for a "landing page" like http://wikiba.se/. But I'll forget these things if you don't write them down :D

I actually think we should go at it the "other" way around, conceptually. I don't know that our audience knows what they're missing - our documentation is not just bad, I think it's a little messy and unclear where to start.
We need base things first, like rationale - why is OOUI working the way it does (the idea of widgets separate from data is pretty crucial, for example, but not immediately thought about outside the people who already work with OOUI) etc etc.

My recommendation is that we should come up with a conceptual ToC for our documentation first, it can start with the basics, and then continue to tutorials. I have a tutorial that I wrote about starting out with OOUI (making a simple "todo" list; see part 1 here and part 2 here) that we can draw on if people like that concept, but I think we should have a lot more substance that is less code-technical and more tutorial-new-user-to-OOUI-friendly.

(added:)

A ToC plan can also keep us organized (since there are multiple people who can/should work on this,) show us what's missing, let us collaborate on writing things, make sure we are on top of how to update those docs when things change, and let the reader/user know what to expect.

We should really try to formulate a plan - and then pick the smaller pieces each of us can do.

I started a list of topics from what seems to me to be a good logical structure here: https://www.mediawiki.org/wiki/User:MSchottlender-WMF/ooui-doc-draft

If people like this, we can see which of those has existing documentation (that perhaps should be improved) and which needs to be written, and then divide the work between those of us who can write it up. I can start writing a few of those, but I don't want to start before I know people approve of the direction or idea itself.

I also think that if we make sure that we add the "basics" we cover both existing (but frustrated) developers who want to use ooui and don't find their documentation -- and also the new potential developers in our community that want to start using OOUI. We can't require standardization if we don't have a place for people to comfortably get into the library and use it, no matter how advanced or new they are.

Personally, the part of the documentation I found missing was info about the inherited behaviours of classes. All the OOUI widgets have a rather complicated inheritence tree, and it was confusing to figure out does widget X support behavior Y which is defined in some other widget that may or may not be a superclass class several levels deep.

In T155473#2957628, @Bawolff wrote:

Personally, the part of the documentation I found missing was info about the inherited behaviours of classes.

That's annoying when looking at the source code, but then not much can be done about that. The generated documentation seems to correctly inherit method docs. (Or do you mean something more specific by "behaviour"?)

We can definitely add documentation about inheritance in ooui. In my proposal toc I have a section about mixins and widgets, and I intended to write inheritance logic and explanation there, to supplement the specifics of the code documtation.

In T155473#2958734, @Tgr wrote:

In T155473#2957628, @Bawolff wrote:

Personally, the part of the documentation I found missing was info about the inherited behaviours of classes.

That's annoying when looking at the source code, but then not much can be done about that. The generated documentation seems to correctly inherit method docs. (Or do you mean something more specific by "behaviour"?)

Hmm. I thought i was looking at the generated docs. Maybe i was mistaken, this was a little while ago.

@Mooeypoo s suggestion and outline makes a lot of sense to me. I remember, when I tried to find out to use OOUI, it was very hard and much was based on reading source code (which sadly created the circular dependency in understanding…).

This project is selected for the Developer-Wishlist voting round and will be added to a MediaWiki page very soon. To the subscribers, or proposer of this task: please help modify the task description: add a brief summary (10-12 lines) of the problem that this proposal raises, topics discussed in the comments, and a proposed solution (if there is any yet). Remember to add a header with a title "Description," to your content. Please do so before February 5th, 12:00 pm UTC.

This was the seventh most popular item in the Developer Wishlist results.

@Volker_E is this something that could be included in the UI standardization project's roadmap? I vaguely remember it being planned anyway...

@Tgr There has been a dedicated session at last October's Editing offsite. It's not necessarily belonging to UI-Standardization roadmap, but various teams. @Prtksxna has collected the current status quo and early ideas at T158494.
We take the vote serious and are discussing how to best move the documentation forward there.

Developer-Advocacy wants to improve the developer experience of newcomers. Is it correct to assume that OOjs UI documentation (and UI-Standardization in general) are essential assets for new developers willing to Do The Right Thing?

In T155473#3039824, @Qgil wrote:

Is it correct to assume that OOjs UI documentation (and UI-Standardization in general) are essential assets for new developers willing to Do The Right Thing?

I would think so, yes.

@Qgil Yes, they both are. The dependency between things like the style guide, automated docs from OOjs UI source code and all MediaWiki documentation and tutorials need closer focus.

In relation to T158149: Find an owner for top 10 Developer Wishlist 2017 proposals, I dare to ask: what is the current status? :)

Hey @Qgil, sorry for the late reply.
The documentation has seen major improvements over the last couple of months, with my personal highlight – the inclusion of code behind the widgets shown in our OOUI demo (“Show code ↓” link aside of every widget). This was largely driven by @Prtksxna and @matmarex and a few other team members.
We also have the ability to link to specific demo widgets now (again, thanks @matmarex), these links needs yet to be used in our main documentation. As simple as that part of the solution sounds, fixing bugs and simplifying code for developers on the code level is higher prioritized and usually also higher valued. Therefore we are not completely done with it. Still optimistic to resolve it largely by end of 2017.

In T155473#3728613, @Volker_E wrote:

Still optimistic to resolve it largely by end of 2017.

@Volker_E: Heja, three years later, could you share what's left to do? And is there anything that others can help with? Thanks in advance!