update the edit process description for docs and blog posts

burningTyger · burningTyger · commit bb998aa93b28 · 2014-11-11T21:20:03.000+01:00
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.
