From 1a6f7611216e032e34963f666ce00125d80dbc68 Mon Sep 17 00:00:00 2001 From: Yuri Ziebell Date: Mon, 4 Mar 2019 11:21:00 +0100 Subject: [PATCH] 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 --- docs/about-us.md | 38 +++++++++++++++++++ docs/github.md | 2 +- docs/gitter.md | 2 +- docs/guide.md | 7 ---- docs/guides-design.md | 7 ++++ .../design-drafts.md} | 11 ++++-- .../getting-started.md} | 34 ++++++++++------- docs/{guides => guides-design}/interaction.md | 12 ++++-- docs/{guides => guides-design}/variables.md | 11 ++++-- docs/guides-dev.md | 7 ++++ docs/{guides => guides-dev}/create-library.md | 10 +++-- docs/{guides => guides-dev}/create-pattern.md | 10 +++-- .../create-properties.md | 8 +++- .../install-local-library.md} | 16 +++----- docs/guides/start.md | 21 ---------- docs/references/reference.md | 2 +- docs/start.md | 27 ++++++++++--- 17 files changed, 144 insertions(+), 81 deletions(-) create mode 100644 docs/about-us.md delete mode 100644 docs/guide.md create mode 100644 docs/guides-design.md rename docs/{guides/design.md => guides-design/design-drafts.md} (89%) rename docs/{guides/essentials.md => guides-design/getting-started.md} (70%) rename docs/{guides => guides-design}/interaction.md (91%) rename docs/{guides => guides-design}/variables.md (91%) create mode 100644 docs/guides-dev.md rename docs/{guides => guides-dev}/create-library.md (99%) rename docs/{guides => guides-dev}/create-pattern.md (96%) rename docs/{guides => guides-dev}/create-properties.md (97%) rename docs/{guides/library.md => guides-dev/install-local-library.md} (92%) delete mode 100644 docs/guides/start.md diff --git a/docs/about-us.md b/docs/about-us.md new file mode 100644 index 000000000..fd3e018cd --- /dev/null +++ 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 index 0ff504b51..f96318251 100644 --- 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 index c11da1ca2..0cecdf91a 100644 --- 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 deleted file mode 100644 index 6430ec852..000000000 --- a/docs/guide.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: guides -displayName: Guides -options: - query: tags=guide - order: 1 ---- diff --git a/docs/guides-design.md b/docs/guides-design.md new file mode 100644 index 000000000..8f6fd3d2f --- /dev/null +++ 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 b/docs/guides-design/design-drafts.md similarity index 89% rename from docs/guides/design.md rename to docs/guides-design/design-drafts.md index 1684fc7d0..7847e5f70 100644 --- a/docs/guides/design.md +++ b/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 b/docs/guides-design/getting-started.md similarity index 70% rename from docs/guides/essentials.md rename to docs/guides-design/getting-started.md index 85b28b3b6..3d9c78c5f 100644 --- a/docs/guides/essentials.md +++ b/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 b/docs/guides-design/interaction.md similarity index 91% rename from docs/guides/interaction.md rename to docs/guides-design/interaction.md index 01ec092ff..ac060ef1d 100644 --- a/docs/guides/interaction.md +++ b/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 b/docs/guides-design/variables.md similarity index 91% rename from docs/guides/variables.md rename to docs/guides-design/variables.md index 39de8a2f3..4d175f4a8 100644 --- a/docs/guides/variables.md +++ b/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 new file mode 100644 index 000000000..05f56f452 --- /dev/null +++ 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 b/docs/guides-dev/create-library.md similarity index 99% rename from docs/guides/create-library.md rename to docs/guides-dev/create-library.md index 7aa64f523..0d39b0909 100644 --- a/docs/guides/create-library.md +++ b/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 b/docs/guides-dev/create-pattern.md similarity index 96% rename from docs/guides/create-pattern.md rename to docs/guides-dev/create-pattern.md index 4499ca9c0..b19774f6f 100644 --- a/docs/guides/create-pattern.md +++ b/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 b/docs/guides-dev/create-properties.md similarity index 97% rename from docs/guides/create-properties.md rename to docs/guides-dev/create-properties.md index 1c05f1180..170caff8e 100644 --- a/docs/guides/create-properties.md +++ b/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 b/docs/guides-dev/install-local-library.md similarity index 92% rename from docs/guides/library.md rename to docs/guides-dev/install-local-library.md index 2fa5eaf68..926174e92 100644 --- a/docs/guides/library.md +++ b/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 deleted file mode 100644 index f4315525d..000000000 --- a/docs/guides/start.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -displayName: Overview -tags: - - guide - - entry -options: - order: -1 ---- - -# Alva Guides -With these guides you will learn how Alva works and how you can use it to supercharge your products. Let’s start! - -You can also download a [Playground](http://media.meetalva.io/file/Website.alva) File of our Website built in Alva to play around. - -## Let’s start - -```widget -const React = require("react"); -const {PatternList} = require("@patternplate/widgets"); -module.exports = () => ; -``` diff --git a/docs/references/reference.md b/docs/references/reference.md index 9b703f020..c7087429c 100644 --- 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 index b7cd9cfb0..377cd805a 100644 --- 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 = () => ; +``` + +## 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 = () => ; +module.exports = () => ; ``` ## Levels @@ -34,7 +51,7 @@ module.exports = () =>