documentation-improvements: improving documentation

[marcelmoreau]

These edits are to make things more obvious to users – specifically Imarcians. I’ll also call out minor changes as well:

• I did not quickly know how to get BPC loaded locally in my browser. To help others, I added the script commands (npm run fractal start, npm run fractal build) under an explicit View Boilerplate Components locally section in the readme.md. I also added the script commands to package.json – it did not have them
• added the npx commands under a more explicit “Using Boilerplate Components in a new project” section
• changed references of Boilerplate to read Boilerplate Components
• changed markdown to use hash-based headings in readme.md – no more underline dash style

[khamer]

• the npm scripts you added don't make sense, are unnecessary, and you don't even use them.
• I'm going to push we rename/archive the existing imarc/boilerplate and replace it with this one, so all the 'Boilerplate Components' replacements don't really make sense either.
• Why are you pushing package-lock.json changes if you're only updating the readmes?

After those things, it'd hard to tell what new documentation you added to be honest - I can tell you added in some links and formatting, but not sure if there's new content too.

[marcelmoreau]

npm run fractal start makes sense to me because that's the only command with which I could get the project to load in my browser. npm run fractal does nothing. it's not documented how to fire this up in a browser. if it is, please tell me where.

npm run fractal build is called in the build script in package.json. if it's unnecessary, why is it there? doesn't one need that to regenerate the build at certain points?

people need to know how to clone and run this. no one does either besides you, tristan, and I and improving this might help foster more involvement.

[marcelmoreau]

IMO, it would be helpful if we took 10-15 minutes at the start of tomorrow's FED meeting and had everyone:

1. clone this on their own
2. see pattern library locally – browse around
3. make a sass edit and see changes in their browser
4. bonus – add a dummy atom locally and see it in their browser

then people feel involved, and they would be set up for contributions. we can see where our documentation needs to be improved. otherwise, people are just passively listening.

[khamer]

I did a pass of improvements, trying to expand in the areas you mentioned, in #47 . If we're good with it, I'll merge it in before the meeting later so we can benchmark off the updates.

https://github.com/imarc/boilerplate-components/blob/better-docs/README.md https://github.com/imarc/boilerplate-components/blob/better-docs/.github/CONTRIBUTING.md

[marcelmoreau]

sure, merge it in