Let's revisit our README.md. File of v0.24.0
Ideas:
Intro
- Be more verbose about library's strengths and key features: Accessibility, em based sizing, number of widgets, modularity, LESS variables comes to mind
- We're mixing terminology, once toolkit, once library. Let's make use of one consistently. Preferably “library”.
“Quick start”
- Clarify and reduce Quick start, remove f.e. “if you don't want to use npm”, grunt-cli is included in grunt, …
“Loading the library”
- Extend loading by using the library?
- Start with what dev would normally need to use and explain further application below.
- “The remaining files make it possible to load only parts of the whole library.” isn't explanatory
“Versioning”
- http://semver.org/ is the only outlined HTTP address. Put it into first sentence.
“Contributing”
- <rant>These two sentences explain on its own, why our software (in general) is not an inviting place to start with becoming a contributor:</rant>
“You will need a Wikitech account which you can use to login to Gerrit, our code review system.
You will need a Wikimedia account, which you can use to login to Phabricator.”
- Add LESS to linted files
- SVGO sounds nice, but isn't integrated into our CI, also why do we have --disable=cleanupIDs as option?
- “You should expect to get code review within a day or two.” sounds nice, maybe a bit optimistic?
- “A new version of the library is cut and released most weeks on Tuesdays.” KISS => “A new version of the library is released most weeks on Tuesdays”
“Release”
It might be helpful, but do we need this here?
Additional ideas:
- Moving “Versioning” further down, underneath “Contributing”
- GitHub: Adding CSS gzip size JS gzip size indicators as seen at https://github.com/twbs/bootstrap
- Adding a “Community” section as seen at https://github.com/twbs/bootstrap
- Adding a copyright and license section
- Adding an explicit Contributing.md file
- Explaining the support of both, PHP and JS side-by-side further
- Like the browser support matrix at Bootstrap, with our architecture it might be hard to integrate. But any link to supported browsers would help contributors as it's about a user interface library!
GitHub Tagline
Currently reads “Modern JavaScript UI toolkit. This is a mirror from https://gerrit.wikimedia.org. See https://www.mediawiki.org/wiki/Developer_access for contributing. Visit the main website for further documentation: https://www.mediawiki.org/wiki/OOjs_UI” turn into
- “Modern JavaScript UI toolkit. Main website: https://www.mediawiki.org/wiki/OOjs_UI. This is a mirror from https://gerrit.wikimedia.org.” Remove contributing link into “Contributing” section.
GitHub Topics
- Already added “ui, ui-components, oojs-ui, icons” to the rather new GitHub topics
Inspirations taken from README Maturity Model – thanks @Jdforrester-WMF, Bootstrap and SemanticUI
Your thoughts are welcome…!