While working on T218229, I couldn’t find any information for developers working on OOUI itself. I put together a draft at User:Lucas Werkmeister (WMDE)/Working on OOUI, but it’s not great (I assume there must be some better build step than a full grunt build
, or perhaps the HTML should use some other JS file that will automatically pull in everything?). If you think something like that would be useful in the OOUI documentation, feel free to use what’s on that page :)
User talk:MSchottlender-WMF/ooui-doc-draft
Unfortunately, right now, we are all "stuck" with using the grunt build
method. There's a grunt quick-build
but from my experience, it's really insufficient. It skips images and a few other things that, in theory, are unnecessary for a quick test of the script, but in effect it tends to be buggy. You can try it, maybe it'll work for what you're trying to do? :\
I usually run the OOUI demos locally while I work on OOUI. So, I clone the OOUI repo and then run
npm install
and grunt build
. Then, I open the oojs-ui-folder/demos/index.html
in a browser.
If I'm fixing a bug, I first try to reproduce it in the demos. If the bug involves a specific set of configuration, I change one of the widgets to have that config (or add another instance of it with the new config). Then I work with the ooui files, and run grunt build
, and recheck the demo.
If I am creating a new widget, I add that widget to the demos (which is good to do anyways!) and then test it through the demos page.
I find that I have to run grunt build
mostly because the .less files must be compiled, and I usually have at least some changes there. It's not an ideal way to work, but I think it might be easier and better than pulling the files manually, and working with the npm package separately.
I was looking for resources to describe ooui to a designer and came across praeclarum's Ooui on github. Since that ooui is the first hit on teh GOOG, it would be helpful to know if there is any relation. They both have similar snippets showing on the search page:
This looks great. Filling in the gaps. :-)
I'll add my rote recommendation to update the existing pages (even if that involves a complete replacement), rather than starting new pages, because M:Grants:Learning patterns/Every new page starts off unwatched. E.g. https://www.mediawiki.org/w/index.php?title=OOjs_UI&action=info has 33 page watchers, and the subpages have fewer but still more-than-zero.
I changed the layout of the proposed ToC to be a table that includes existing pages (Assuming I didn't forget any)
From my quick glance on each, there are a few that we might want to split up and many we will want to rewrite, especially the introductory ones.
But I am hoping it's a start!
Oh, absolutely - the idea is to use existing pages (Which there are many) when possible - but the point of the ToC is to get a sense of the organization of the pages, what we have vs. what we're missing, and serve as a "todo" list for collaborating on documentation writing.
Also, the ToC can set the "spirit" of the documentation in general, which means that we could then get into the existing pages and improve them based on what is missing, etc.
So this is just supposed to give us a direction and galvanize the documentation "working group"; there are a bunch of pages we will need to write from scratch, but also a whole lot that we could already put in as existing.