rubinius · brixen · Nov 11, 2014 · Nov 11, 2014 · Nov 11, 2014 · yorickpeterse
diff --git a/_posts/2014-11-11-rubinius-3-0-part-2-the-process.markdown b/_posts/2014-11-11-rubinius-3-0-part-2-the-process.markdown
@@ -16,7 +16,7 @@ Our priority is to have an _impact_, providing value to people using Rubinius. W
 
 > If it doesn't work when someone tries it, they may wait a long time before trying it again, if ever.
 
-There are several problems with this fallacy. It confuses local and global effects. For every one person for whom a feature did not work, there are an unknown number of people for whom some feature did work. The latter group may have a much bigger global affect than the one person. It also does not account for the cost of people waiting for features. Finally, it's rooted in fear. The best antidote to fear is facts. If engagement is important, we should measure engagement and take steps to improve it.
+There are several problems with this fallacy. It confuses local and global effects. For every one person for whom a feature did not work, there are an unknown number of people for whom some feature did work. The latter group may have a much bigger global effect than the one person. It also does not account for the cost of people waiting for features. Finally, it's rooted in fear. The best antidote to fear is facts. If engagement is important, we should measure engagement and take steps to improve it.
 
 Now that we know what to *not* do, what should we do? To understand that, we need to question how we release software.
 
@@ -36,7 +36,7 @@ The fact that features are constantly being developed does not mean that a syste
 
 As opposed to mechanical systems, biological systems are *very well adapted* to functioning as a whole while changing or growing. Consider the difference between a plant growing from a seed and building a car. It's only at the very end of the manufacturing process that a car is able to function as a whole. Meanwhile, the fundamental metabolic processes in a plant function from the very beginning. The plant changes as it grows, so not every part is functional at the start. The key is to decide which parts should function first.
 
-Another important aspect of biological systems is where the boundaries lie. There are cellular boundaries, system boundaries, and the organism as a whole, which has a boundary between itself and its environment. These boundaries serve the dual purpose of keeping things separate but in contact. Along with these boundaries, different parts of a biological system have different degrees of resilience. For example, a skeleton versus soft tissue. These two concepts&#151;boundaries and joining different types of resilience&#151;can be useful in understanding software release. I'll return to them later.
+Another important aspect of biological systems is where the boundaries lie. There are cellular boundaries, system boundaries, and the organism as a whole, which has a boundary between itself and its environment. These boundaries serve the dual purpose of keeping things separate but in contact. Along with these boundaries, different parts of a biological system have different degrees of resilience. For example, a skeleton versus soft tissue. These two concepts&#151;boundaries and joining different types of resilience&#151;can be useful in understanding software releases. I'll return to them later.
 
 ### Releasing Costs A Lot
 
@@ -77,7 +77,7 @@ Besides changing the focus of the release process, we are adding a feature to Ru
 The first time you start Rubinius after a fresh installation, if the setting does not already exist, you'll get a message like the following:
 
     Rubinius is able to automatically install new versions. Installing
-    a new version will not overwrite you existing version.
+    a new version will not overwrite your existing version.
 
     Enable this feature? ([Y]es, [n]o, [a]uto, ne[v]er, [h]elp):
 

diff --git a/doc/en/how-to/write-a-blog-post.markdown b/doc/en/how-to/write-a-blog-post.markdown
@@ -14,35 +14,34 @@ experiences using or developing Rubinius.
 The preferred format for blog posts is Markdown. However, if you have special
 formatting needs, the post can be written in HTML directly.
 
-Clone Rubinius repository as that is where the website and posts are stored.
+Clone Rubinius repository as that is where the website and posts are stored:
 
-    git clone https://github.com/rubinius/rubinius.git
+    git clone https://github.com/rubinius/rubinius.github.io.git
 
-To get started, ensure you have the `kramdown` and `jekyll` gems installed.
+To get started, ensure you have the `github-pages` gem installed. Use
+`bundler` inside your local clone directory:
 
-    rbx gem install jekyll kramdown
+    rbx -S bundle install
 
-Now go to the posts directory
+Now go to the posts directory:
 
-    cd rubinius/web/_posts
+    cd _posts
 
 Create a file in the console using the filename format `YYYY-MM-DD-perma-link.markdown`.
 
     touch "%(date +"%Y-%m-%d")-perma-link-title.markdown"
 
-Write your brilliant post.
+Write your brilliant post:
 
     cat /dev/random > <<the file post>> # :-p
 
-Run jekyll to compile the website, including your post.
+Run jekyll to serve the website locally, including your post:
 
-    cd ../web/
-    rbx -S jekyll build
+    rbx -S jekyll serve --watch
 
-Create a commit of all the changes in the `web/` directory.
+Once you are happy with the results create a commit of your post:
 
-    cd ../
-    git add web/
+    git add _posts/
     git commit -m "Wrote a blog post on ....."
 
 Submit a patch, pull request, or if you have commit rights, push the commit to

diff --git a/doc/en/how-to/write-documentation.markdown b/doc/en/how-to/write-documentation.markdown
@@ -10,16 +10,16 @@ next_url: how-to/translate-documentation
 The Rubinius documentation is integrated with the website and blog. It uses
 Jekyll just like the other components.
 
-To get started, ensure you have the `kramdown` and `jekyll` gems installed.
+To get started, use `bundler` inside your local repository clone:
 
-    rbx gem install jekyll kramdown
+    rbx -S bundle install
 
-The documentation source is under the `web/doc` directory. There are
+The documentation source is under the `doc` directory. There are
 subdirectories for each language to which the documentation has been
 translated (eg `en`, `es`, etc.).
 
 There is a Table of Contents for each translation (e.g.
-`/web/doc/en/index.markdown`). The rest of the documentation consists of
+`doc/en/index.markdown`). The rest of the documentation consists of
 single files that have YAML attributes to specify how the documents are
 connected. Essentially, the documentation can be viewed as a doubly-linked
 list of documents with each document pointing to the previous and next
@@ -49,38 +49,26 @@ title and link for the next document. These are used to enhance browsing the
 documentation and limiting the amount of work necessary to re-order parts of
 the documentation.
 
-Both the source for the documentation and the files generated by Jekyll are
-committed to the Rubinius repository. When people clone the source repository,
-they can run `rake docs` to view the documentation before they have built
-Rubinius or if having problems building Rubinius.
-
-
 ### Editing Existing Documentation
 
 An initial outline for the documentation has been created. There are many
 topics that merely need to have documentation written for them.
 
 To add documentation for an existing topic or to fix existing documentation:
 
-1. Open the file for the topic under `web/doc/LANG`.
+1. Open the file for the topic under `doc/LANG`.
 1. Add or improve the documentation.
 1. To view your updates while you are working on them, run
-   `rbx -S jekyll serve --watch` in the `web/` directory.
+   `rbx -S jekyll serve --watch` in the root directory.
 1. Once finished adding or editing documentation, commit your changes to the
    source files.
-1. Run `rbx -S jekyll build` in the `web/` directory to force update of all
-   generated files in `web/_site`.
-1. Commit the generated files. If making a small change, the generated files
-   can be committed with the documentation source files. If making many
-   changes, commit the generated files separately to make reviewing changes
-   more simple.
 
 
 ### Adding New Documentation
 
 To add documentation for which no existing topic exists:
 
-1. Create a new file with the .markdown extension under `web/doc/LANG`.
+1. Create a new file with the .markdown extension under `doc/LANG`.
 1. Set up the attributes to link the new file into the existing files. This
    will require editing the _previous_ and _next_ attributes of the existing
    files to insert the new file, as well as adding an entry to
@@ -90,9 +78,3 @@ To add documentation for which no existing topic exists:
 1. Edit the new file using Markdown syntax.
 1. Once finished adding or editing documentation, commit your changes to the
    source files.
-1. Run `rbx -S jekyll build` in the `web/` directory to force update of all
-   generated files in `web/_site`.
-1. Commit the generated files. If making a small change, the generated files
-   can be committed with the documentation source files. If making many
-   changes, commit the generated files separately to make reviewing changes
-   more simple.