[tracking] READMEs as documentation

Question

[tracking] READMEs as documentation

nathanstilwell opened this issue 4 years ago · comments

We have a couple of READMEs in the repo, but I think at a minimum we should have one at the root of every package.

Lauren Barker · Answer 1 · Thu May 07 2020 04:47:09 GMT+0800 (China Standard Time)

#44 adds development commands to the main README and in the comments there is some more context around those. We should probably define what goes in the README.md vs CONTRIBUTING.md though because it's unclear to me. cc @j-low

Lauren Barker · Answer 2 · Sat May 30 2020 00:46:16 GMT+0800 (China Standard Time)

Following up on defining what goes in each doc:

My confusion about what goes into our CONTRIBUTING.md vs README.md is because our installation and publishing instructions are in CONTRIBUTING.md. Those instructions are typically in the README.md so that's where I would look for them. Also, we put build/installation instructions for each package in that package's README.md so it is kind of inconsistent.

After looking into this a bit more, I think we should move the installation and publishing information to the README.md. Right now I think we are mixing contribution guidelines and getting started instructions.

Nathan Stilwell · Answer 3 · Thu Jul 09 2020 01:57:04 GMT+0800 (China Standard Time)

circling back to this based on conversations we been having recently. A couple of things,

README should define usage and user context about the package they are located in.
CONTRIBUTING should contain information about developing inside of the UI repo. We also recently made the decision to have only one top level CONTRIBUTING file. Where there are differences in development among the packages, that complexity should be obfuscated behind npm lifecycle scripts.

There may be details that don't fall into either of these categories, but in general if it is for users of UI libraries it goes in a README and if it is for developers of UI libraries it goes in CONTRIBUTING.