Documentation improvements

README.md

@@ -4,16 +4,32 @@
 
 # Vivid UI components ![develop build](https://github.com/Vonage/vivid/workflows/develop%20build/badge.svg?branch=develop)
 
-[vivid.vonage.com for demos](https://vivid.vonage.com)
+Vivid provides a Design System comprised of ready-to-use web components and services, aligned with the Vonage's design guidelines, providing well-thought APIs and striving to stick to the best practices in every possible aspect.
 
-### Roadmap
+Demos, tutorials and living examples are at [vivid.vonage.com](https://vivid.vonage.com).
 
-Vivid project is set to deliver Vonage's own design system for the company project's front-ends.
+Contributor guidance is [here](docs/contributing.md).
+
+---
+
+#### Consumption
+
+Our deliveries are available as GitHub packages, they are privately accessible within Vonage organization.
+
+Please visit [Vivid packages page](https://github.com/Vonage/vivid/packages) to enlist our latest releases. You may further drill into each package to read its specific documentation, review previous versions etc.
+
+GitHub packages may be consumed via various build systems, please refer to [this documentation](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem) for more details.
+
+Obviously, most likely Vivid products will be consumed as **npm** dependencies in **package.json**, specific documentation on that is located [here](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages#installing-a-package).
+
+---
+
+#### Roadmap
 
 The system contains these aspects:
-- general services/facilities like fonts management, scheme management and alike
+- general services/facilities (fonts management, scheme management etc)
 - atomic/generic components
-- high level business specific components
+- high level business-logic specific components
 
 The overall roadmap may be split into the the following:
 * alpha (0.0.x versions; alpha-romeo :)) - initial release (month to few months?), deliverables of this release are likely to have breaking changes
@@ -58,6 +74,7 @@ The overall roadmap may be split into the the following:
 | `<vwc-radio>` | - | planned | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+radio) |
 | `<vwc-scheme-select>` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/235304) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+scheme+schema+theme+select) |
 | `<vwc-select>` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/235301) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+select) |
+| `<vwc-slider>` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/251037) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+slider) |
 | `<vwc-switch>` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/235302) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+switch) |
 | `<vwc-table>` | - | planned | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+table) |
 | `<vwc-textfield>` | [![GPR](https://img.shields.io/static/v1?label=GPR&message=0.0.7&color=green&logo=github)](https://github.com/Vonage/vivid/packages/166369) | in progress | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+textfield) |
@@ -71,39 +88,16 @@ The overall roadmap may be split into the the following:
 | `<vwc-dialer>` | - | planned | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+dialer) |
 | `<vwc-video>` | - | planned | [*Issues*](https://github.com/Vonage/vivid/issues?q=is%3Aissue+is%3Aopen+video+player+videoplayer) |
 
-
-### Get up and running
-
-* Clone the repo
-* Run `yarn` (repo relies on yarn workspaces) in order to build the repo once / bring the dependencies
-* Run the following steps as the normal build-and-see flow:
- * `yarn compile` - builds `css` from `scss`, compiles `ts` into `js`
- * `yarn dev:server` - runs dev server on `localhost` in order to see the demo pages
- * OR `yarn start` - is a shortcut for `compile` and `dev:server`, for your convenience
- * AND `yarn watch` - observes & compiles scss / ts files in src folders. Run it in a separate terminal window in order to watch changes occur while editing files.
-* Navigate to `https://localhost:5424/index.html` (replace the port if needed) and start hacking with the components in the browser
-* Welcome! :)
-
 ---
 
-
-## Scripts
-
-- `yarn` does initial installation of the dependencies (yarn is preferred here for a fast resolution)
-- `compile` compiles typescript, scss etc
-- `start` runs demo app for development (will auto trigger `compile` command beforehand), reloading on file changes
-- `test` runs test suite with Karma
-- `lint` runs the linter for your project
-- `build` builds demo app for production
-
-
-## Issues
+#### Issues
 
 We use GitHub Issues as the official bug tracker for **Vivid** Please check the [existing issues](https://github.com/vonage/vivid/issues). It's possible someone has already reported the same problem.
 
 If your problem or idea is not addressed yet, [open a new issue](https://github.com/vonage/vivid/issues/new).
 
+---
 
-## Suggestions
+#### Suggestions
 
 Go through the [board](https://github.com/vonage/vivid/projects/1) to search for existing feedbacks and share yours if not already addressed.

docs/contributing.md

@@ -0,0 +1,65 @@
+# Contributor guideline
+
+Vivid team is dedicated to deliver and support the services and the components for the front end teams across the Vonage.
+
+Yet, we believe that this project should be managed as an open source, within the organization.
+Contributions are most welcome.
+
+As with any other platform-like case, responsibility for a stable and quality code for all requires some process to be followed and some reasonable gatekeepers to pass over.
+
+---
+
+#### Process
+
+##### Feature request
+
+When a team needs some service or component which feels like suitable for a broader usage, we advise first to see an existing stuff, [packages](https://github.com/Vonage/vivid/packages) and [demo](vivid.vonage.com) are the best places to refer to.
+
+If the desired thing was not found, please consult with an [issues](https://github.com/Vonage/vivid/issues) and [features](https://github.com/Vonage/vivid/projects), it is possible something is already in the pipe.
+
+If yet nothing similar found, create a new feature request / issue. Of course, everyone is more than welcome to contact Vivid team directly too.
+
+Important! We do ask to follow this process even if the one is going to implement the feature her/himself.
+
+##### Coding time
+
+Have you decided to implement something cool as part of the Vivid project? Great! We'd like to help you with that so that the dev-experience would be excellent.
+Below are few intos, but most important - is something doesn't feel right, please talk to us.
+We won't promise that everything will be fixed as we are opinionated people as well, but we'll definitely listen carefully and try to solve things.
+
+###### Getting up and running
+
+* clone the repo
+* run `yarn` (repo relies on yarn workspaces) in order to build the repo once / bring the dependencies
+* run the following steps as the normal build-and-see flow:
+ * `yarn compile` - builds `css` from `scss`, compiles `ts` into `js`
+ * `yarn dev:server` - runs dev server on `localhost` in order to see the demo pages
+ * OR `yarn start` - this is a shortcut for `compile` and `dev:server`, for your convenience
+ * `yarn watch` - watches for changes in scss / ts files in src folders and recompiles whatever is needed (run in another terminal)
+* navigate to `http://localhost:5424/index.html` and start hacking with the components in the browser
+* Welcome! :)
+* just before getting into the change, please make sure to branch out from the `develop` branch, giving your branch some good and descriptive name
+* during the coding time, it is best to sync with `develop` rather frequently, we'll do our best to keep it evergreen
+
+###### Coded, looks okay, now quality time
+
+In order to ensure certain level of quality we rely on automation.
+But even before you code hits the CI you can run some preliminary checks locally:
+* `yarn lint` - runs the linter (ESLint) on your code (I'm always surprised how it finds typos in my best crafted code :))
+* `yarn test` - runs test suite (Karma); this one will ensure that you've not broken stuff of anyone else; but it is even better to add you own tests to the new functionality too, trust us, you'll sleep better this way :)
+
+> We do have a coverage collected (Istanbul) but its level is not yet enforced at this point. Full report may be found in a nice UI layout in the coverage folder after the tests ran.
+
+###### All good, let' deliver
+
+When you happy with what you've done, please open a PR back to the `develop` branch.
+You may specify reviewer if relevant.
+
+Done! Well, there probably will be some exchange of comments and fixes, but eventually your PR will be merged into the `develop` branch, which will eventually be taken to release branch and finally pushed to production.
+
+---
+
+
+#### Useful scripts
+
+- `build` builds demo app for production