Good documentation has several parts. Which parts do we want to focus on? Where should they live? Should we break down this task?
API Documentation
I'd say this is in pretty good state right now. Though the jsduck interface can be a bit hard to use sometimes, it does have a lot of information. Places where this documentation can live
- jsduck
- jsduck alternatives that are easier on the eye and probably easier to use?
- replicated to mediawiki - T95060: Documentation for OOUI widgets needs to list what methods are available for each widget
- ???
Guides and tutorials
What we have
What we need
- More gadget specific guides
- Specific tutorials like
- How to make a dialog and retrieve information from it
- How to make your own widgets (Part 1 of 42)
Where this should live
- jsduck lets you make guides
- mediawiki
- links to people's blogs from mediawiki
- ???
Demos
We currently have a demo page that we use mostly for testing. The page does not do much good to showcase the library or to help learn how to use it. There are also editable live code examples inside the API docs (for example the CheckboxInputWidget, try changing the code and clicking live preview), but they are hard to discover and the UI isn't great either.
@Volker_E recently had an idea of using codepen or something like it exclusively for demos. This is a great idea because it makes helping others easy. Also forking existing codepens is a good starting point when learning.
Where this should live
- as jsduck inline examples
- an extension on mediawiki T118126: OOUI documentation on mediawiki.org should be more interactive (use real inputs, not screenshots of inputs)
- codepen
- the current demo page T128550: Ensure we're fully demoing OOUI in the demos
- @Mooeypoo and others had the idea of being able to see and copy the code behind the widgets on the demo page
- ???
Questions and answers
A single place where everyone asks their queries, it helps other people find answers without asking.
Where this should live
- [[ https://stackoverflow.com/tags/oojs-ui/ | StackOverflow tag oojs-ui ]]
- A talk/flow page
- ???