Component README discussion
- Dominant language
- No language data
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
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.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the component READMEs and the proposed README contents in this issue. Identify where shared Discipl-wide documentation should live, including guidance for node.js, npm, mocha, babel, and common dependencies. Done would require an agreed README standard and a clear location for the referenced shared documents.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- babel, node.js
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100