adjusted docs and README

jonasjabari · jonasjabari · commit fad7b20b53a6 · 2020-11-04T13:29:52.000+01:00
diff --git a/README.md b/README.md
diff --git a/docs/reactive_apps/100-rails_integration/README.md b/docs/reactive_apps/100-rails_integration/README.md
@@ -2,6 +2,50 @@
 
 Matestack apps and pages are connected to Rails through controllers and controller actions. HTTP requests are handled through classic Rails routing and responded through Rails controller actions. Just let the controller action render Matestack page instead of a Rails view at the end. Optionally you can use apps on controller or action level in order to wrap the page with a layout written in pure Ruby.
 
+## JavaScript Setup
+
+Matestack's JavaScript needs to be integrated into your Rails application in order to use the reactive, JavaScript driven features. You can use Webpacker (recommended) or Rails assets pipeline to do this.
+
+### Webpacker
+
+Add 'matestack-ui-core' to your `package.json` by running:
+
+```
+$ yarn add https://github.com/matestack/matestack-ui-core#v1.1.0
+$ yarn install
+```
+
+This adds the npm package that provides the JavaScript corresponding to the matestack-ui-core ruby gem. Make sure that the npm package version matches the gem version. To find out what gem version you are using, you may use `bundle info matestack-ui-core`.
+
+Next, import 'matestack-ui-core' in your `app/javascript/packs/application.js`
+
+```js
+import MatestackUiCore from 'matestack-ui-core'
+```
+
+and compile the JavaScript code with webpack:
+
+```
+$ bin/webpack --watch
+```
+
+**When you update the matestack-ui-core gem, make sure to update the npm package as well.**
+
+### Asset Pipeline
+
+If you are using the asset pipeline, you don't need to install the separate npm package. All required JavaScript libraries are provided by the matestack-ui-core gem.
+
+Require 'matestack-ui-core' in your `app/assets/javascript/application.js`
+
+```javascript
+//= require matestack-ui-core
+```
+
+### Turbolinks
+
+We recommend to (remove/deactivate)(https://stackoverflow.com/a/38649595) turbolinks, as there is no reason to use it alongside matestack-ui-core and there might appear some strange side effects. If you encounter strange page-transition/form-submit/action-submit behavior and have turbolinks activated, try to deactivate it first.
+
+
 ## Rails layouts still required
 
 Even if a Matestack app defines the layout of the UI, you need a classic Rails layout in order to get things running:
diff --git a/docs/reactive_components/100-rails_integration/README.md b/docs/reactive_components/100-rails_integration/README.md
@@ -1,8 +1,10 @@
 # Rails integration
 
+## JavaScript Setup
+
 Matestack's JavaScript needs to be integrated into your Rails application in order to use the reactive, JavaScript driven features. You can use Webpacker (recommended) or Rails assets pipeline to do this.
 
-## Webpacker
+### Webpacker
 
 Add 'matestack-ui-core' to your `package.json` by running:
 
@@ -27,7 +29,7 @@ $ bin/webpack --watch
 
 **When you update the matestack-ui-core gem, make sure to update the npm package as well.**
 
-## Asset Pipeline
+### Asset Pipeline
 
 If you are using the asset pipeline, you don't need to install the separate npm package. All required JavaScript libraries are provided by the matestack-ui-core gem.
 
@@ -37,7 +39,7 @@ Require 'matestack-ui-core' in your `app/assets/javascript/application.js`
 //= require matestack-ui-core
 ```
 
-## Turbolinks
+### Turbolinks
 
 We recommend to (remove/deactivate)(https://stackoverflow.com/a/38649595) turbolinks, as there is no reason to use it alongside matestack-ui-core and there might appear some strange side effects. If you encounter strange page-transition/form-submit/action-submit behavior and have turbolinks activated, try to deactivate it first.
 
diff --git a/docs/start/100-installation/README.md b/docs/start/100-installation/README.md
@@ -2,7 +2,7 @@
 
 This guide shows you how to add matestack-ui-core to an existing rails application.
 
-If you want to use Matestack's optional reactivity features, please follow this [guide](/docs/reactivity/100-rails-integration/) after performed the following steps for basic installation:
+If you want to use Matestack's optional reactivity features, please follow this [guide](/docs/reactive_components/100-rails-integration/) after performed the following steps for basic installation:
 
 ## Installation
 
diff --git a/docs/start/200-about/README.md b/docs/start/200-about/README.md
@@ -0,0 +1,22 @@
+# About Matestack
+
+## Who we are
+
+We are a small team of passionated Ruby developers commited to put everything we have into creating sustainable Ruby gems simplifying web software development for developers around the world. The core members of our team are Nils ans Jonas working from Dresden and Berlin, Germany. Jonas as the founder of the company is working full time at matestack. Nils contributes as a working stundent part time and writes his master's thesis about matestack's technology. In Februar 2021 he wants to join full time! We're Ruby developers but take different roles at the company: Jonas once created the first versions of `matestack-ui-core` starting in 2018 but has now transitioned to handling business, management, sales and marketing. Nils joined 2020 and is now taking the engineering lead role, managing our tech development.
+
+We are a bootstrapped company offering software development/consulting services to our clients and at the same time creating open source Ruby gems. The revenue earned from our services is used to invest more time implementing and maintaining our gems. We do not get money from investors.
+
+## Why we do what we do
+
+We are passionated Ruby developers. In specific: we love to create web applications based on Ruby On Rails.
+
+In order to create dynamic, app-like web applications, we once started to create fullblown JavaScript applications and reduced Rails to a pure JSON API. Using this common approach, compared to the classic single-repo MVC structure, we increased the complexity in our development by introducing a separate full-blown frontend framework. Implementing two separate systems (backend-api, frontend-app) is a pain: Two different code bases, two repositories to maintain, two different deployment schedules, two test environments, two everything...! And then add native app development for iOS and Android on top of that! Being a small dev team, we decided not to adopt this modern web development complexity and decided to create... `matestack-ui-core`!
+
+`matestack-ui-core` enables us to define sophisticated UI behavior in pure Ruby without touching JavaScript and HTML. We end up writing 50% less code while increasing productivity, maintainability and developer happiness. We love it and want to share that gift with other Ruby developers around the world.
+
+The main goals are:
+
+- Reduction of complexity of modern web development, moving front and backend closer together
+- More maintainable UI code, using a component-based structure written in Ruby
+- Increased development speed and happiness, offering prebuilt UI-Components for typical requirements
+- Modern, dynamic UI feeling without the need to implement a separate JavaScript Application
diff --git a/docs/start/300-community/README.md b/docs/start/300-community/README.md
@@ -0,0 +1,16 @@
+# Community
+
+We're happy about every single active community member. Asking questions, creating GitHub Issues, adjusting things through PRs... every kind of community activity counts!
+
+## Discord server
+
+Once started with a Gitter chat, we moved to a Discord server in November 2020. Join [here](https://discord.gg/c6tQxFG) in order to get support while creating awesome stuff with Matestack! Happy to see you there!
+
+## Weekly Q/A sessions
+
+In order to help you with any issues around Matestack, we offer free, personal Q/A sessions two times a week:
+
+- Tuesday, 10 AM CET
+- Thursday, 6 PM CET
+
+ Join [here](https://discord.gg/c6tQxFG) to get the links to the video calls, shared a bit in advance of each Q/A session.
diff --git a/docs/start/400-contribute/README.md b/docs/start/400-contribute/README.md
@@ -1,6 +1,7 @@
 # Core Contribution
+
 We are very happy about anyone that wants to improve this project! Please make sure to read this guide before starting your work to avoid unnecessary trouble down the road!
-Always feel welcomed to reach out to us via [Gitter](https://gitter.im/basemate/community) or mail if you are unsure or need further information.
+Always feel welcomed to reach out to us via [Discord](https://discord.gg/c6tQxFG) or mail if you are unsure or need further information.
 
 ## What to work on
 
diff --git a/docs/start/README.md b/docs/start/README.md
@@ -1,27 +1,25 @@
 # Matestack UI Core Docs
 
-Welcome to the docs of the Ruby gem `matestack-ui-core`, enabling you to easily create component based (reactive) web UIs in pure Ruby on top of your Rails applications.
+Welcome to the docs of the Ruby gem `matestack-ui-core`!
 
-The docs cover following main topics:
+Matestack enables you to craft maintainable web UIs in pure Ruby, skipping ERB and HTML. UI code becomes a native and fun part of your Rails app. Thanks to reactive core components, reactivity can be optionally added on top without writing JavaScript, just using a simple Ruby DSL.
 
-- Installation and general information
-- UI components in pure Ruby
-- Reactive components in pure Ruby
-- Reactive apps in pure Ruby
+You end up writing 50% less code while increasing productivity, maintainability and developer happiness. Work with pure Ruby. If necessary, extend with pure JavaScript. No Opal involved.
 
+The docs cover following main topics:
 
-## [Installation](/docs/start/100-installation/)
+**[Installation](/docs/start/100-installation/)**
 
 Learn how to properly set up and update matestack-ui-core with your existing Rails application.
 
-## [UI components in pure Ruby](/docs/ui_components/README.md)
+**[UI components in pure Ruby](/docs/ui_components/README.md)**
 
 Craft your UI based on your components written in pure Ruby. Utilizing Ruby's amazing language features, you're able to create a cleaner and more maintainable UI implementation.
 
-## [Reactive components in pure Ruby](/docs/reactive_components/README.md)
+**[Reactive components in pure Ruby](/docs/reactive_components/README.md)**
 
 What about going even one step further and implement **REACTIVE** UIs in pure Ruby? Matestack's reactive core components can be used with a simple Ruby DSL enabling you to create reactive UIs without touching JavaScript!
 
-## [Reactive apps in pure Ruby](/docs/reactive_apps/README.md)
+**[Reactive apps in pure Ruby](/docs/reactive_apps/README.md)**
 
 The last step in order to leverage the full Matestack power: Create app (~Rails layout) and page (Rails ~view) classes and implement dynamic page transitions without any JavaScript implementation required.
diff --git a/docs/ui_components/README.md b/docs/ui_components/README.md
@@ -28,13 +28,6 @@ end
 
 Such a component is defined within your application. We call them custom components. While implementing these, you use Matestack's core components in order to define your UI: Above we used methods like `heading`, `paragraph`, `img` and `div`. These are all what we call core components provided trough a core component registry which is automatically loaded. These core components representing the corresponding HTML tags. Calling `div` for example would result in `<div></div>`  after rendering. Matestack provides a always expanding wide set of w3c's specified HTML tags, enabling you to write UIs in pure Ruby. All available components are listed in our [components api](/docs/api/100-components/).
 
-## Accessing data in components
-
-In components you have access to your helpers and all Rails helpers. You don't have access to controller instance variables, because components should be reusable everywhere and therefore not depend on instance variables set in controller actions.
-
-To access data inside components we can define required and/or optional properties which are passed to the component via hash and used with getter methods in the component. Our `card` for example requires a body in order to show a minimal Bootstrap card.
-
-
 ## Component registry
 
 In order to use your custom component we need to register the component. We therefore need to create a component registry. We could place it anywhere we want, but we recommend placing it inside the components folder. It is possible to have multiple component registries, for example to keep shop components seperated from management components. Create a file called `registry.rb` in `app/matestack/components/`.
@@ -93,3 +86,9 @@ class Components::Products::Detail < Matestack::Ui::Component
 end
 
 ```
+
+## Accessing data in components
+
+In components you have access to your helpers and all Rails helpers. You don't have access to controller instance variables, because components should be reusable everywhere and therefore not depend on instance variables set in controller actions.
+
+To access data inside components we can define required and/or optional properties which are passed to the component via hash and used with getter methods in the component. Our `card` for example requires a body in order to show a minimal Bootstrap card.
