Gutenberg: Docs: Improve packages readme

Created on 11 Oct 2018 · 6Comments · Source: WordPress/gutenberg

Packages need better readme to be descriptive and informative for clarity.

Some packages readmes are oneliner or missing details.

Ref https://github.com/WordPress/gutenberg/pull/10510#discussion_r224445644

cc: @chrisvanpatten

Packages Checklist:

[ ] a11y
[ ] api-fetch
[ ] autop
[ ] babel-plugin-import-jsx-pragma
[ ] babel-plugin-makepot
[ ] babel-preset-default
[ ] blob
[ ] block-library
[ ] blocks
[ ] block-serialization-default-parser
[ ] block-serialization-spec-parser
[ ] browserslist-config
[ ] components
[ ] compose
[ ] core-data
[ ] custom-templated-path-webpack-plugin
[ ] data
[ ] date
[ ] deprecated
[ ] dom
[ ] dom-ready
[ ] editor
[ ] edit-post
[ ] element
[ ] a11y
[ ] api-fetch
[ ] autop
[ ] babel-plugin-import-jsx-pragma
[ ] babel-plugin-makepot
[ ] babel-preset-default
[ ] blob
[ ] block-library
[ ] blocks
[ ] block-serialization-default-parser
[ ] block-serialization-spec-parser
[ ] browserslist-config
[ ] components
[ ] compose
[ ] core-data
[ ] custom-templated-path-webpack-plugin
[ ] data
[ ] date
[ ] deprecated
[ ] dom
[ ] dom-ready
[ ] editor
[ ] edit-post
[ ] element
[ ] escape-html
[ ] hooks
[ ] html-entities
[ ] i18n
[ ] is-shallow-equal
[ ] jest-console
[ ] jest-preset-default
[ ] keycodes
[ ] library-export-default-webpack-plugin
[ ] list-reusable-blocks
[ ] npm-package-json-lint-config
[ ] nux
[ ] plugins
[ ] postcss-themes
[ ] redux-routine
[ ] rich-text
[ ] scripts
[ ] shortcode
[ ] token-list
[ ] url
[ ] viewport
[ ] wordcount
[ ] escape-html
[ ] hooks
[ ] html-entities
[ ] i18n
[ ] is-shallow-equal
[ ] jest-console
[ ] jest-preset-default
[ ] keycodes
[ ] library-export-default-webpack-plugin
[ ] list-reusable-blocks
[ ] npm-package-json-lint-config
[ ] nux
[ ] plugins
[ ] postcss-themes
[ ] redux-routine
[ ] rich-text
[ ] scripts
[ ] shortcode
[ ] token-list
[ ] url
[ ] viewport
[ ] wordcount

Audit Checklist:

A detailed description of the package
Simple installation instructions (npm install @wordpress/components --save)
Usage instructions for ES5 and ES6, or links to appropriate sub-readmes if necessary

[Type] Documentation [Type] Enhancement [Type] Task

Source

ajitbohra

All 6 comments

@ajitbohra A good starting point for this might be to create a list of the packages as a checkbox list, and also come up with standards to audit the readmes/descriptions.

I think as a baseline, each package should meet the following criteria:

Simple, readable package description, explaining the broad purpose of the package
Readme containing…
- More detailed description of the package
- Simple installation instructions (npm install @wordpress/components --save and ES2015 instructions)
- Usage instructions for ES5 and ES6, or links to appropriate sub-readmes if necessary

I know @tofumatt has many good opinions on documentation and might have additional criteria for us to consider.

chrisvanpatten on 11 Oct 2018

👍1

I frankly think ES5 instructions aren't really worth it, but I'm not sure if that's official WordPress policy 😄

Those sound like a great start to me, not much to add. Only thing is how usable they even are outside WordPress and what the intended audience is for each package. Some are better supported outside of a WordPress context and some are just packages whose target is WordPress. It's worth explicitly saying so to set expectation of support, see:
https://github.com/WordPress/gutenberg/pull/10429#pullrequestreview-162946474

I'd definitely like to see this.

tofumatt on 12 Oct 2018

👍1

@tofumatt That's actually a good point — if you're consuming the packages via npm it may be safe to assume that you have an ES6/webpack setup, especially because the scripts themselves use ES6 and need to be transpiled anyway.

ES5 examples are important in the editor documentation, but not so much in the README that we push to npm.

chrisvanpatten on 12 Oct 2018

And they definitely bloat the docs, which can be scary for those (like me) that often skim docs of new packages rather than read them thoroughly at first. 😅

tofumatt on 12 Oct 2018

👍1

Agree with @tofumatt less is more, same here I often skim docs 😅

@chrisvanpatten that checklist looks good for audit will add the checkbox checklist of the packages. Will try to split out the list into two one with content which needs to be reviewed structured which you can have a look at. Another list with the packages that need content will add the rough draft and you can cover me on the copy my writing skills suck 😅

ajitbohra on 12 Oct 2018

I'm closing this one out, per all the work @nosolosw has done here: https://github.com/WordPress/gutenberg/issues/14227