Merge pull request #456 from cucumber/feature/refactor-documentation

Refactor documentation

features/README.md

@@ -12,12 +12,12 @@
 Your benefits:
 
 * Test any command line application implemented in any [programming
-  language](https://github.com/cucumber/aruba/tree/master/features/getting_started/supported_programming_languages.feature) -
+  language](https://app.cucumber.pro/projects/Aruba/documents/master/features/01_getting_started_with_aruba/supported_testing_frameworks.feature) -
   e.g. Bash, Python, Ruby, Java, ...
 * Manipulate the file system and the process environment with helpers working similar like tools you may know from your shell
 * No worries about leaking state: The file system and the process environment will be reset between tests
 * Support by a helpful and welcoming community – see our [Code of Conduct](https://github.com/cucumber/cucumber/blob/master/CODE_OF_CONDUCT.md)
-* The [documentation](https://github.com/cucumber/aruba/tree/master/features/) is our contract with you. You can expect `aruba` to work as documented
+* The [documentation](https://app.cucumber.pro/projects/aruba) is our contract with you. You can expect `aruba` to work as documented
 
 Our Vision:
 
@@ -28,7 +28,7 @@ Our Vision:
 Our Focus:
 * Test the user-interaction with the commands at runtime &ndash; this excludes the process of installation/deployment of commands like installing Rubygems with `gem install <your-gem>`.
 
-## Install
+# Install
 
 Add this line to your application's `Gemfile`:
 
@@ -48,45 +48,28 @@ Or install it yourself as:
 gem install aruba
 ~~~
 
-## Usage
+# Usage
 
-Please also see this
-[feature test](https://github.com/cucumber/aruba/tree/master/features/getting_started/supported_testing_frameworks.feature)
+**Note:** Please also see this
+[feature test](https://app.cucumber.pro/projects/Aruba/documents/master/features/01_getting_started_with_aruba/supported_testing_frameworks.feature)
 for the most up to date documentation.
 
-### Initialize your project with "aruba"
+## Getting started
 
-There's an initializer to make it easier for you to getting started. If you
-prefer to setup `aruba` yourself, please move on to the next section.
-
-1. Go to your project's directory
-
-2. Make sure, it's under version control and all changes are committed to your
-   version control repository
-
-3. Run one of the following commands depending on the tools you use to test your project.
-
-   This assumes, that you use either `rspec`, `cucumber-ruby` or `minitest` to
-   write the tests for your project. Besides that, your tool can be implemented
-   in any programming language you like.
+1. Clone the "Getting Started" application and make the cloned repository your current working directory
 
    ~~~bash
-   aruba init --test-framework rspec
-   aruba init --test-framework cucumber
-   aruba init --test-framework minitest
+   git clone https://github.com/cli-testing/aruba-getting-started.git
+   cd aruba-getting-started
    ~~~
 
-### Your First Tests with "aruba"
-
-1. Clone the "Getting Started" application and install its dependencies
+2. Install the required dependencies
 
    ~~~bash
-   git clone https://github.com/cli-testing/aruba-getting-started.git
-   cd aruba-getting-started
    bundle install
    ~~~
 
-#### Cucumber
+### Cucumber
 
 1. Create a file named "features/support/env.rb" with:
 
@@ -116,10 +99,9 @@ prefer to setup `aruba` yourself, please move on to the next section.
    bundle exec cucumber
    ~~~
 
-#### RSpec
+### RSpec
 
-1. Create a file named "spec/spec_helper.rb" with the following content. If the
-   file already exists add the line to the file.
+1. Add the following line to the "spec/spec_helper.rb" file.
 
    ~~~ruby
    require 'aruba/rspec'
@@ -151,9 +133,9 @@ prefer to setup `aruba` yourself, please move on to the next section.
    bundle exec rspec
    ~~~
 
-#### Minitest
+### Minitest
 
-1. Add a file named "test/test_helper.rb" with:
+1. Add the following line to the "test/test_helper.rb" file.
 
    ~~~ruby
    require 'aruba/api'
@@ -162,8 +144,6 @@ prefer to setup `aruba` yourself, please move on to the next section.
 3. Add a file named "test/use_aruba_with_minitest.rb" with:
 
    ~~~ruby
-   $LOAD_PATH.unshift File.expand_path('../test', __FILE__)
-
    require 'test_helper'
    require 'minitest/autorun'
 
@@ -189,12 +169,33 @@ prefer to setup `aruba` yourself, please move on to the next section.
 4. Run your tests
 
    ~~~bash
-   bundle exec ruby -Ilib:test test/use_aruba_with_minitest.rb
+   bundle exec ruby -I lib:test test/use_aruba_with_minitest.rb
    ~~~
 
 A full documentation of the API can be found
 [here](http://www.rubydoc.info/github/cucumber/aruba/master/frames).
 
-## Copyright
+# Initialize an existing project
+
+There's an initializer to make it easier for you to get started.
+
+1. Go to your project's directory
+
+2. Make sure it's under version control and all changes are committed to your
+   version control repository
+
+3. Run one of the following commands depending on the tools you use to test your project.
+
+   This assumes, that you use either `rspec`, `cucumber-ruby` or `minitest` to
+   write the tests for your project. Besides that, your tool can be implemented
+   in any programming language you like.
+
+   ~~~bash
+   aruba init --test-framework rspec
+   aruba init --test-framework cucumber
+   aruba init --test-framework minitest
+   ~~~
+
+# Copyright
 
 Copyright (c) 2010-2017 Aslak Hellesøy et al. See [MIT License](LICENSE) for details.