discipl / discipl/main

Component README discussion

Open
#1 1 comment 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.