feat: update doc structure and content

# Conflicts: # docs/guides-design/getting-started.md # docs/guides/start.md # docs/start.md # packages/site/src/hero.tsx
meetalva · May 18, 2019 · 1a6f761 · 1a6f761 · marionebl · May 18, 2019
1 parent 0f6244a
commit 1a6f761
Show file tree

Hide file tree

Showing 17 changed files with 144 additions and 81 deletions.
diff --git a/docs/about-us.md b/docs/about-us.md
@@ -0,0 +1,38 @@
+---
+displayName: The story behind Alva
+options:
+  order: 1
+---
+
+# The story behind Alva
+**In today’s tool landscape, oldtimers like Photoshop and slightly newer tools like Sketch still play their roles. This means there are multiple sources of truth, making it hard to find out which truth is the real one. We try to design interactive products with static tools.**
+
+To change that, Alva consumes component libraries to let users create complex compositions of real components.
+
+```
+„Even the most ‚advanced‘ digital design tools are based on workflows for drawing mere pictures of interfaces.“
+–Daniel Eden, Facebook Product Designer
+```
+
+## Alva’s mission is to put an end to static and sandboxed tools that create more problems in today’s environment than they solve.
+
+!(youtube:https://www.youtube.com/embed/gZT13EKfZXg)
+
+The overall goal is to bring concept, design and engineering closer together by linking them through a strong toolchain (of which Alva of course is just one of several tools). Product teams shall be liberated from many chores of maintenance to focus more on innovation instead.
+
+This should mean less waste and less faults, lead to better products and bring more freedom for designers and engineers. Alva aims to enable
+
+* **friction-less** design by bringing web technology into web design, and
+* **interactivity as the next dimension** of visual interface design by instant prototyping.
+
+## During the next years, the team wants to go for
+
+* **new ways of interaction** beyond visual interface design, e.g. voice, chat, gestures and facial expressions,
+* **complex, contextual design** based on device data, user environment, preferences and behaviour,
+* **automated design** by setting up the design system instead of specific screens, and the future of design through an entirely open architecture and open source code.
+
+
+
+## »Alva« is the middle name of Thomas Alva Edison, who made electricity available to the public.
+
+Alva started in August 2017 as an initiative at SinnerSchrader and since then a quite small, but very powerful cross-functional product design and engineering team is working hard on building and evolving the Alva app and its ecosystem. We learned a lot from the engineering world, where most of the tools and platforms are open source. That’s why we decided to make Alva entirely open source, too. To give something back to the community.
diff --git a/docs/github.md b/docs/github.md
@@ -1,5 +1,5 @@
 ---
-displayName: GitHub
+displayName: Alva repo on GitHub
 options:
   href: https://github.com/meetalva/alva
   order: 100

diff --git a/docs/gitter.md b/docs/gitter.md
@@ -1,5 +1,5 @@
 ---
-displayName: Gitter
+displayName: Chat with us
 options:
   href: https://gitter.im/meetalva/Lobby
   order: 101

diff --git a/docs/guide.md b/docs/guide.md
diff --git a/docs/guides-design.md b/docs/guides-design.md
@@ -0,0 +1,7 @@
+---
+name: guides-design
+displayName: Prototyping with Alva
+options:
+  query: tag=guide AND tag=design
+  order: 3
+---
diff --git a/docs/guides/design.md → docs/guides-design/design-drafts.md b/docs/guides/design.md → docs/guides-design/design-drafts.md
@@ -1,13 +1,16 @@
 ---
-displayName: Guide 2 – Design Drafts
+displayName: 4. Add design drafts
 
 tags:
   - guide
----
+  - design
+  - rapid
 
-# Guide 2 - Add Design Drafts
+options:
+  order: 4
+---
 
-:woman_student: **Level**: Beginner
+# Add Design Drafts
 
 ---
 

diff --git a/docs/guides/essentials.md → docs/guides-design/getting-started.md b/docs/guides/essentials.md → docs/guides-design/getting-started.md
@@ -1,19 +1,21 @@
 ---
-displayName: Guide 1 – Essentials
+displayName: 1. Get started
 
 tags:
   - guide
----
-
-# Guide 1 – Essentials
-
-:woman_student: **Level**: Beginner
+  - design
 
+options:
+  order: 1
 ---
 
-In this guide you'll take your very first steps with Alva.
+# Get started
 
+In this guide you'll start your first Alva project and connect a publicly available component library.
 
+[Image]
+
+---
 
 ## 1. Download and install
 
@@ -23,7 +25,7 @@ We fully support macOS and Windows systems and provide untested images for vario
 
 Next, locate the Alva image in your Downloads and double-click on the file to start the installation process.
 
-## 2. Start Alva for the first time
+## 2. Start Alva
 
 Alva should install into your applications folder. Depending on your operating system and
 its configuration the exact location may vary. E.g. for macOS it is `/Applications/Alva`. 
@@ -33,14 +35,20 @@ Find the Alva logo and double-click it to start. Alva should greet you with the
 ![](https://media.meetalva.io/alva-greeting.png)
 
 
-## 3. Create a new file and add content to it
+## 3. Create a new file and connect a library
 
-Click on `Create new Alva File`. You'll find a list of essential patterns on the bottom left of the next screen.
-Locate the `Text` pattern and drop it onto the element pane right above the patterns list.
+Click on `Create File` and then switch from `Design` to `Library` view in the top left panel. You find a continously growing list of  public component libraries.
 
-![](https://media.meetalva.io/guides/guide-01-01.gif)
+Locate the `Alva Website Design` library and click on `Connect`.
 
-That’s it – we just added your first component to our prototype!
+[Image]
+
+That’s it – you connected your first Design System with Alva!
+
+## 4. Add a text component
+ Go back to the `Design` view. You find the library's components in the bottom left panel. Locate the `Text` component and drop it onto the element pane right above the component list.
+
+![](https://media.meetalva.io/properties.png)
 
 ## 3. Adjust a Property
 After you've selected the newly added text component, have a look at the right side of Alva. That is where all the **properties** – like settings – of the component are shown. In our case there is just a single one – the text value. Let’s **change** that to `Hello Alva!`.

diff --git a/docs/guides/interaction.md → docs/guides-design/interaction.md b/docs/guides/interaction.md → docs/guides-design/interaction.md
@@ -1,13 +1,16 @@
 ---
-displayName: Guide 4 – Interaction
+displayName: 2. Link pages via interaction
 
 tags:
   - guide
----
+  - design
+  - interaction
 
-# Guide 4 - Interaction
+options:
+  order: 2
+---
 
-:woman_student: **Level**: Beginner
+# Link pages via interaction
 
 ---
 
@@ -18,6 +21,7 @@ On the left side of Alva all of the pages are shown. Let’s **add a page** and
 
 ![](https://media.meetalva.io/guides/guide-03-01.gif)
 
+
 ## 2. Add Button
 We need an interactive component. Let’s **add a button**, for example.
 

diff --git a/docs/guides/variables.md → docs/guides-design/variables.md b/docs/guides/variables.md → docs/guides-design/variables.md
@@ -1,13 +1,16 @@
 ---
-displayName: Guide 5 – Variables
+displayName: 3. Use variables in inputs
 
 tags:
   - guide
----
+  - design
+  - variables
 
-# Guide 5 - Variables
+options:
+  order: 3
+---
 
-:woman_student: **Level**: Intermediate
+# Use variables in inputs
 
 ---
 

diff --git a/docs/guides-dev.md b/docs/guides-dev.md
@@ -0,0 +1,7 @@
+---
+name: guides-dev
+displayName: Build for Alva
+options:
+  query: tag=guide AND tag=dev
+  order: 4
+---
diff --git a/docs/guides/create-library.md → docs/guides-dev/create-library.md b/docs/guides/create-library.md → docs/guides-dev/create-library.md
@@ -1,13 +1,15 @@
 ---
-displayName: Guide 8 - Create Library
+displayName: 4. Create a custom library
 
 tags:
   - guide
----
+  - dev
 
-# Guide 8 - Create a Component Library
+options:
+  order: 4
+---
 
-:woman_student: **Level**: Expert
+# Create a Custom Component Library
 
 ---
 

diff --git a/docs/guides/create-pattern.md → docs/guides-dev/create-pattern.md b/docs/guides/create-pattern.md → docs/guides-dev/create-pattern.md
@@ -1,13 +1,15 @@
 ---
-displayName: Guide 6 - Create a Pattern
+displayName: 2. Create a component
 
 tags:
   - guide
----
+  - dev
 
-# Guide 6 - Create a Pattern
+options:
+  order: 2
+---
 
-:woman_student: **Level**: Intermediate
+# Create a Component
 
 ---
 

diff --git a/docs/guides/create-properties.md → docs/guides-dev/create-properties.md b/docs/guides/create-properties.md → docs/guides-dev/create-properties.md
@@ -1,11 +1,15 @@
 ---
-displayName: Guide 7 - Create Properties
+displayName: 3. Add properties
 
 tags:
   - guide
+  - dev
+
+options:
+  order: 3
 ---
 
-# Guide 7 - Create Properties
+# Adding Properties to a Component
 
  Learn how to make your patterns configurable with property interfaces.
 

diff --git a/docs/guides/library.md → docs/guides-dev/install-local-library.md b/docs/guides/library.md → docs/guides-dev/install-local-library.md
@@ -1,21 +1,17 @@
 ---
-displayName: Guide 3 - Connect a Library
+displayName: 1. Install a local library
 
 tags:
   - guide
----
-
-#  Guide 3 - Connect a Pattern Library
-
-:woman_student: **Level**: Intermediate
+  - dev
 
+options:
+  order: 1
 ---
 
-> If you want to skip this guide, feel free to download our [Playground Alva-File](http://media.meetalva.io/file/Website.alva) with a pre-connected library to proceed.
-
----
+# Install a Local Library
 
-> :information_source: This guide teaches how to connect an Alva project to the ready-made Alva Design Library. 
+> :information_source: This guide teaches how to connect an Alva project to a local library with the Alva Design Library as example. 
 
 > For a guide on how to create a custom pattern library from scratch, see [Create a custom Library](./doc/docs/guides/create-library?guides-enabled=true).
 

diff --git a/docs/guides/start.md b/docs/guides/start.md
diff --git a/docs/references/reference.md b/docs/references/reference.md
@@ -2,5 +2,5 @@
 displayName: Reference
 options:
   query: tags=reference
-  order: 1
+  order: 5
 ---
diff --git a/docs/start.md b/docs/start.md
@@ -5,19 +5,36 @@ options:
 ---
 
 # Documentation
-We’re happy that you made the way to our docs. Here you can find [Guides](#guides) and [References](#references). 
-All doc items state the recommended [skill level](#levels):woman_student:. 
+**Welcome to Alva! Alva lets you design interactive products based on the same components your engineers are using for production websites. Basically, Alva is design and engineering, joined together. [Learn more about our story](about-us).**
+
+![](https://media.meetalva.io/alva-library-production.png)
+
 
-## Guides
+## Guides: Prototyping with Alva
 
 Instructions for common use cases that can be followed step by step. 
 This is where you'll want to begin when exploring Alva and its features.
 Most guides are written **for beginners**.
 
+![](https://media.meetalva.io/alva-design-to-code.png)
+
+```widget
+const React = require("react");
+const {PatternList} = require("@patternplate/widgets");
+module.exports = () => <PatternList query="is=doc AND tag=guide AND tag=design AND tag!=entry" />;
+```
+
+## Guides: Creating a Component Library
+
+Learn how to create your own Design System's component library based on React/Typescript and how to bring it to live in Alva.
+
+![](https://media.meetalva.io/component-list-abstraction.png)
+
+
 ```widget
 const React = require("react");
 const {PatternList} = require("@patternplate/widgets");
-module.exports = () => <PatternList query="is=doc AND tag=guide AND tag!=entry" />;
+module.exports = () => <PatternList query="is=doc AND tag=guide AND tag=dev AND tag!=entry" />;
 ```
 
 ## Levels
@@ -34,7 +51,7 @@ module.exports = () => <PatternList query="is=doc AND tag=guide AND tag!=entry"
 
 ## References
 
-Detailed technical documentation about various Alva features. References are written with **intermediate users** in mind. 
+Currently Alva supports React and certain library requirements, but the goal is to be platform-agnostic in the future.
 
 ```widget
 const React = require("react");