Component README discussion

[pimotte]

The READMEs for our various components tend to lack a little bit. Currently, they are either very short, or very long. In the latter case often with outdated information.

I'd like to discuss what a README should or should not contain.

Rough proposal:

READMEs must contain:

• Short description of the functionality of the package
• Description how to run tests
• Link to a discipl-wide page with information on how to work with the stack (node.js, npm, mocha, babel, dependencies that we used commonly (e.g. loglevel). Note that this page does not exist at the moment)

READMEs should contain:

• List of discipl-specific components that it depends on, and what they are used for

READMEs may contain:

• A link to a discipl-wide vision document, which explains the place of the component in the bigger discipl vision.
• A link to a respository-specific design document, which details the design direction for the component
• A list of major dependencies, with their role in the component.

READMEs must not contain:

• Information that is inaccurate for the current implementation. Future design goals should be in the vision or design documents.

I would say the place for the discipl-wide documents is this repo, which is why I created the issue here.

[pimotte]

Also maybe consider what to do with jsdoc, maybe: discipl/core#21