Rethink the README structure
elisechant opened this issue · comments
If you empathise with how someone will use this repo, most people will clone, then in the first or second commit replace README content altogether with content relevant to their project.
Knowing this, our README could be more useful with that usage pattern in mind.
What if we instead:
Firstly, thought about the README more like a what, why, then a checklist of set up steps?
This gives people just enough information to know what this is, then just enough information to get cracking.
Consider this:
# Monorepo-starter
[describe why?] Everything you need to set up you create a monorepo. Maintained by @Ben and @Mitchell. Help at [Issues](https://github.com/Thinkmill/monorepo-starter/issues) or [#monorepo]() in Thinkmill Slack.
[describe how] Create a new repo from this Starter, Click Github's "Use this template" button.
[picture of the "Use this template" button, with link to Github's docs]
[divider]
Great! you started a new monorepo!
Here's what to do now:
1. Create a directory for your new website
`cd website`
`npx create-react-app`
2. Install dependencies
`yarn`
3. Run your dev loop
`yarn start` or whatever this would be
Need more documentation about monorepos? We've got you covered at [Monorepo-guide](https://github.com/Thinkmill/monorepo)
Secondly, think about moving content that we intend the user to keep at hand (that being a very condensed version of the monorepo-guide, and very specific to this repo, such as run scripts documentation) to either an informative CLI or to another file monorepo-manual.md.
my-monorep
├── README.md
└── monorepo-manual.md
