first set of revisions - Getting started (bitrise-io#47)

docs/getting-started/builds-and-workflows.md

@@ -1,29 +1,52 @@
 # Builds & Workflows
 
-A *build* is the process specified by the app's *workflow*, which is a collection of *steps*. Every step is an [**open source**](https://github.com/bitrise-io/bitrise-steplib) script repository which you can inspect and modify.
+A *build* is the process specified by the app's *workflow*, which is a collection of *steps*.
+Every step is an **open source** repository which you can inspect, modify,
+and run with the [open source Bitrise CLI](https://www.bitrise.io/cli).
 
-A Workflow is interpreted as a `yaml`, which you are able to modify at bitrise.io's Workflow editor, or [yaml editor](http://blog.bitrise.io/2016/02/12/edit-your-yaml-files-like-a-boss.html) directly. On the graphical UI of the Workflow editor, you are able to add, remove, and reorder the build steps. Steps represent a block of script execution with predefined input and output variables. Steps can be written in various languages we (our virtual machines) support, like bash, Go, Ruby, Swift, etc. Read more about how workflows and steps are implemented on our [engineering blog](https://tech.bitrise.io/decentralized-automation/).
+The app's build configuration can be specified as a `yaml` (`bitrise.yml`) config,
+which you can modify in [bitrise.io](https://www.bitrise.io)'s Workflow editor (on your app's Bitrise.io page click the `Workflows` tab),
+or [yaml editor](http://blog.bitrise.io/2016/02/12/edit-your-yaml-files-like-a-boss.html) directly.
 
-When a build is running, these scripts will be downloaded and executed in the order you've defined in your workflow, with the input parameters you set. They will produce the predefined outputs set as environment variables.
+On the graphical UI of the Workflow editor, you are able to add, remove, and reorder the build steps.
+Steps represent a block of script execution with predefined input and output variables.
+Steps can be written in various languages, like bash, Go, Ruby, Swift, etc.
+Read more about how workflows and steps are implemented on our [engineering blog](https://tech.bitrise.io/decentralized-automation/).
 
-## The build process
-
-There are a lot of things that can be customized when working with Bitrise. The build process has some mutable dimensions as well, from several kind of triggers, through different stacks and preparation types to environment variables.
-
-1. Trigger builds by
-  * clicking the "Build" button on the application's page (runs manually)
-  * scheduling with a selected branch and frequency (runs when scheduled)
-  * [webhook](doc:adding-webhooks)  - after each push or pull request to the given branch (runs when push/pull request arrives)
-  * our [Build Trigger API](doc:build-trigger-api)
+When a build is running, these scripts will be downloaded and executed in the order you've defined in your workflow,
+with the input parameters you set. They will produce the predefined outputs set as environment variables.
 
-2. Environment preparation
-Once we've found a suitable machine, a virtual machine will be provisioned and prepared to run the build. Read more about our virtual machines in [Virtual machines](doc:virtual-machines). Build specific environment variables are preset, so you can use these in your steps. Read more about our available stacks and preparation types in [Available Stacks](doc:available-stacks).
-
-3. Concurrency
-Builds over your subscription plan's concurrency count will be marked as *on hold*. They will start whenever your ongoing builds are finished and you have a free build slot. You can always [purchase additional concurrencies](https://www.bitrise.io/me/profile/pricing) with the Pro plan.
-
-4. Workflow execution
-Steps in Workflows are executed in the same order as defined in the Workflow editor of your application, from top to bottom. You can reorder the steps by dragging. The log each step generates will be displayed on the build's details page.
+## The build process
 
-5. Cleanup
-After the execution of the build, there will be a summary of the build created and stored on the Bitrise server and **the virtual machine gets rolled back to a predefined state**, erasing every file and every change your build made so your code/files woudn't fall into the wrong hands.
+There are a lot of things that can be customized when working with Bitrise.
+The build process has some mutable dimensions as well,
+from several kind of [triggers](https://bitrise-io.github.io/devcenter/webhooks/trigger-map),
+through different stacks and preparation types to environment variables.
+
+1. Trigger builds by:
+    * clicking the `Build` button on the application's page (manual build trigger)
+    * scheduling with a selected branch and frequency (runs when scheduled - you can find this option in the `Build` popup)
+    * [webhook](https://bitrise-io.github.io/devcenter/webhooks) - after each code/tag push or pull request to the given branch (runs when push/pull request arrives)
+    * our `Build Trigger API`
+
+2. Environment preparation:
+   Once we've found a suitable machine, a virtual machine will be provisioned and prepared to run the build.
+   Build specific environment variables are preset, so you can use these in your steps.
+   You can find more information about the available `Stacks` on your app's `Settings` tab,
+   in the `Stack Selector` section.
+
+3. Concurrency:
+   Builds over your subscription plan's concurrency count will be marked as __on hold__.
+   They will start whenever your ongoing builds are finished and you have a free build slot.
+   You can always [purchase additional concurrencies](https://www.bitrise.io/me/profile/pricing) with the Pro plan
+   to increase the concurrent builds you can run at the same time.
+
+4. Workflow execution:
+   Steps in Workflows are executed in the same order as defined in the Workflow editor of your application,
+   from top to bottom. You can reorder the steps by dragging.
+   The log each step generates will be displayed on the build's details page.
+
+5. Cleanup:
+   After the execution of the build, there will be a summary of the build
+   created and stored on the Bitrise server and **the virtual machine gets destroyed**,
+   so your code/files woudn't fall into the wrong hands.

docs/getting-started/code-security.md

@@ -1,14 +1,33 @@
-To guarantee the security of your builds we use [virtual machines](/infrastructure/virtual-machines) for builds. Every build runs in its own, clean virtual machine and we discard the whole virtual machine after the build finishes, erasing every file your build uses and every change you make during your build.
+To guarantee the security of your builds we use [virtual machines](/infrastructure/virtual-machines) for builds.
+Every build runs in its own, clean virtual machine and we discard the whole virtual machine after the build finishes,
+erasing every file your build uses and every change you make during your build.
 
-This way your builds are always protected by changes made by others and from your previous builds, no one else can access your code and you can use a stable environment to define your build workflow (no state persists between builds).
+_This is also true for the Linux/Android stacks, which use Docker containers to run the build.
+The build itself still gets a full virtual machine where no other Docker container is started,
+only the one used as the environment of the build. In short we only use Docker containers
+to manage the environment, not for build environment isolation - that's ensured by using
+full virtual machines for every build._
+
+This way your builds are always protected by changes made by others and from your previous builds,
+no one else can access your code and you can use a stable environment to define your build workflow (no state persists between builds).
 
 ## Source code
-We don't store your source code. The source code is only accessed on the build machines (virtual machines) the way you define it in your Bitrise Configuration (workflow). If you don't have a Git Clone step in your configuration, then the source code won't be touched at all. At the end of the build the whole Virtual Machine is destroyed.
+
+We don't store your source code. The source code is only accessed on the build machines (virtual machines)
+the way you define it in your Bitrise Configuration (workflow). If you don't have a Git Clone step in your configuration,
+then the source code won't be touched at all. At the end of the build the whole Virtual Machine is destroyed.
 
 ## Code signing and other files
-The files you upload in the Workflow Editor (**Code Signing & Files** section of the editor) are stored on `Amazon S3` in a way that it's only accessible for the web servers.
 
-The required credentials are not stored in any database, it is only available in the web servers' environment. Build servers can't access the files directly either. When a build starts the web server generates a read-only, time limited access URL for these files, using [Amazon S3 presigned URLs](https://docs.aws.amazon.com/aws-sdk-php/v3/guide/service/s3-presigned-url.html).
+The files you upload in the Workflow Editor (**Code Signing & Files** section of the editor)
+are stored on `Amazon S3` in a way that it's only accessible for the web servers.
+
+The required credentials are not stored in any database, it is only available in the web servers' environment.
+Build servers can't access the files directly either.
+When a build starts the web server generates a read-only,
+time limited access URL for these files, using [Amazon S3 presigned URLs](https://docs.aws.amazon.com/aws-sdk-php/v3/guide/service/s3-presigned-url.html).
 
 ## Passwords
-Passwords are stored in a hashed, encrypted form. We are encrypting the passwords with [bcrypt algorithm](https://en.wikipedia.org/wiki/Bcrypt), using multiple stretches.
+
+Passwords are stored in a hashed, encrypted form.
+We are encrypting the passwords with [bcrypt algorithm](https://en.wikipedia.org/wiki/Bcrypt), using multiple stretches.

docs/index.md

@@ -1,4 +1,41 @@
-**Feel free to edit any page & to send us a Pull Request!!**
+In short Bitrise is a [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration)
+and [Delivery](https://en.wikipedia.org/wiki/Continuous_delivery) (CI/CD) Platform as a Service (PaaS)
+with a main focus on mobile app development (`iOS`, `Android`, `Xamarin`, ...).
+
+__Automate the testing and deployment of your apps with just a few clicks.__
+
+When you trigger a build a Virtual Machine is assigned to host
+your build and your defined Workflow (series of build Steps) will be executed, step by step.
+
+A `Workflow` consists of one or more build `Steps` (open source git repositories
+which can be executed with the [open source Bitrise CLI](https://www.bitrise.io/cli)).
+[You can create and share your own build Steps too](https://github.com/bitrise-steplib/step-template).
+You are able to define more workflows for the very same app,
+and define [triggers](https://bitrise-io.github.io/devcenter/webhooks/trigger-map/) to specify which workflow should be selected for
+which trigger.
+
+The steps can do anything that can be implemented a command line scripts / programs:
+send emails, [text messages](https://github.com/bitrise-io/steps-sms-text-message),
+pass values to each other, [create Xcode archives](https://github.com/bitrise-io/steps-xcode-archive),
+gather system information about the Virtual Machine
+running the build, notify other users (e.g. on Slack)
+or even [publish to iTunes Connect](https://github.com/bitrise-io/steps-deploy-to-itunesconnect-deliver), and many more.
+You can read more at [Builds and Workflows](/getting-started/builds-and-workflows).
+
+After a build is finished the Virtual Machine is destroyed and you can browse
+the logs of every step that ran during the workflow.
+You can read more at [Code Security](/getting-started/code-security).
+
+
+## Offline CLI
+
+To run a Bitrise build on your machine, you can install our [open source runner](https://www.bitrise.io/cli)
+and use the `bitrise` command to execute your workflows locally.
+It's a great help when you're developing steps, debugging builds,
+or just want to use Bitrise for [any kind of automation](https://github.com/bitrise-io/steps-random-quote) on your machine.
+
+
+## Feel free to edit any page of this DevCenter and to send us a Pull Request!!
 
 !!! note "Edit on GitHub / in your browser directly!"
     You can edit the pages on GitHub directly,
@@ -10,4 +47,4 @@
 
 If you don't want to edit the page on GitHub,
 feel free to [contact us](https://www.bitrise.io/contact),
-and we'll do the change for you!
+and we'll do the change for you!

mkdocs.yml

@@ -4,9 +4,8 @@ repo_name: 'GitHub'
 repo_url: 'https://github.com/bitrise-io/devcenter'
 
 pages:
-- Bitrise DevCenter: index.md
+- "Bitrise DevCenter - What is Bitrise?": index.md
 - Getting Started:
-  - What is Bitrise?: getting-started/index.md
   - Builds & Workflows: getting-started/builds-and-workflows.md
   - Code Security: getting-started/code-security.md
 - Infrastructure: