Sync website docs with README.md and content-sample/index.md

_docs/config.md

@@ -3,35 +3,24 @@ toc:
     config:
         _title: Config
         url-rewriting: URL Rewriting
-nav: 4
+nav: 6
 ---
 
 ## Config
 
-You can override the default Pico settings (and add your own custom settings)
-by editing `config/config.php` in the Pico directory. For a brief overview of
-the available settings and their defaults see [config/config.php.template](https://github.com/picocms/Pico/blob/master/config/config.php.template). To
-override a setting, copy `config/config.php.template` to `config/config.php`,
-uncomment the setting and set your custom value.
+You can override the default Pico settings (and add your own custom settings) by editing `config/config.php` in the Pico directory. For a brief overview of the available settings and their defaults see [`config/config.php.template`][ConfigTemplate]. To override a setting, copy `config/config.php.template` to `config/config.php`, uncomment the setting and set your custom value.
 
 ### URL Rewriting
 
-Picos default URLs (e.g. http://example.com/pico/?sub/page) already are very
-user friendly. Pico anyway offers you an URL rewrite feature to make URLs even
-more user friendly (e.g. http://example.com/pico/sub/page).
+Picos default URLs (e.g. http://example.com/pico/?sub/page) already are very user friendly. Pico anyway offers you an URL rewrite feature to make URLs even more user friendly (e.g. http://example.com/pico/sub/page).
 
-If you're using the Apache web server, URL rewriting should be enabled
-automatically. If you get an error message from your web server, please make
-sure to enable the `mod_rewrite` module. Assumed rewritten URLs work, but Pico
-still shows no rewritten URLs, force URL rewriting by setting
-`$config['rewrite_url'] = true;` in your `config/config.php`.
+If you're using the Apache web server, URL rewriting should be enabled automatically. If you get an error message from your web server, please make sure to enable the `mod_rewrite` module. Assumed rewritten URLs work, but Pico still shows no rewritten URLs, force URL rewriting by setting `$config['rewrite_url'] = true;` in your `config/config.php`.
 
-If you're using Nginx, you can use the following configuration to enable
-URL rewriting. Don't forget to adjust the path (`/pico/`; line `1` and `4`)
-to match your installation directory. You can then enable URL rewriting by
-setting `$config['rewrite_url'] = true;` in your `config/config.php`.
+If you're using Nginx, you can use the following configuration to enable URL rewriting. Don't forget to adjust the path (`/pico/`; line `1` and `4`) to match your installation directory. You can then enable URL rewriting by setting `$config['rewrite_url'] = true;` in your `config/config.php`.
 
     location /pico/ {
         index index.php;
         try_files $uri $uri/ /pico/?$uri&$args;
     }
+
+[ConfigTemplate]: https://github.com/picocms/Pico/blob/master/config/config.php.template

_docs/contribute.md

@@ -1,13 +1,24 @@
 ---
 toc:
     contribute: Contribute
-nav: 6
+nav: 8
 ---
 
 ## Contribute
 
-Are you are interested in contributing to the development of Pico?
+You want to contribute to Pico? We really appreciate that! You can help making Pico better by [contributing code][PullRequests] or [reporting issues][Issues], but please take note of our [contribution guidelines][ContributionGuidelines]. In general you can contribute in three different areas:
 
-For the basics of creating a __plugin__, __theme__ or even contributing to the __Pico core__, we've setup a comprehensive set of [development documentation]({{ site.base_url }}/plugin-dev.html) to get you started.
+1. Plugins & Themes: You're a plugin developer or theme designer? We love you guys! You can find tons of information about how to develop plugins and themes at http://picocms.org/plugin-dev.html. If you have created a plugin or theme, please add it to our [Wiki][], either on the [plugins][WikiPlugins] or [themes page][WikiThemes]. Maybe we will then promote your plugin or theme on [our website][OfficialPlugins] as officially supported!
+2. Documentation: We always appreciate people improving our documentation. You can either improve the [inline user docs][EditInlineDocs] or the more extensive [user docs on our website][EditUserDocs]. You can also improve the [docs for plugin and theme developers][EditDevDocs]. Simply fork Pico from https://github.com/picocms/Pico, change the Markdown files and open a [pull request][PullRequests].
+3. Picos Core: The supreme discipline is to work on Picos Core. Your contribution should help *every* Pico user to have a better experience with Pico. If this is the case, fork Pico from https://github.com/picocms/Pico and open a [pull request][PullRequests]. We look forward to your contribution!
 
-You may also refer to our [class documentation]({{ site.base_url }}/phpDoc/master) for a deeper understanding of Pico's underlying code.
+[OfficialPlugins]: http://picocms.org/plugins.html
+[Wiki]: https://github.com/picocms/Pico/wiki
+[WikiPlugins]: https://github.com/picocms/Pico/wiki/Pico-Plugins
+[WikiThemes]: https://github.com/picocms/Pico/wiki/Pico-Themes
+[Issues]: https://github.com/picocms/Pico/issues
+[PullRequests]: https://github.com/picocms/Pico/pulls
+[ContributionGuidelines]: https://github.com/picocms/Pico/blob/master/CONTRIBUTING.md
+[EditInlineDocs]: https://github.com/picocms/Pico/blob/master/content-sample/index.md
+[EditUserDocs]: https://github.com/picocms/Pico/tree/gh-pages/_docs
+[EditDevDocs]: https://github.com/picocms/Pico/tree/gh-pages/_plugin-dev

_docs/creating-content.md

@@ -4,23 +4,14 @@ toc:
         _title: Creating Content
         text-file-markup: Text File Markup
         blogging: Blogging
-nav: 2
+nav: 4
 ---
 
 ## Creating Content
 
-Pico is a flat file CMS, this means there is no administration backend or
-database to deal with. You simply create `.md` files in the `content-sample`
-folder and that becomes a page. For example, this file is called `index.md`
-and is shown as the main landing page.
+Pico is a flat file CMS, this means there is no administration backend or database to deal with. You simply create `.md` files in the `content-sample` folder and that becomes a page. For example, this file is called `index.md` and is shown as the main landing page.
 
-If you create a folder within the content folder (e.g. `content-sample/sub`)
-and put an `index.md` inside it, you can access that folder at the URL
-`http://yoursite.com/?sub`. If you want another page within the sub folder,
-simply create a text file with the corresponding name and you will be able to
-access it (e.g. `content-sample/sub/page.md` is accessible from the URL
-`http://yoursite.com/?sub/page`). Below we've shown some examples of locations
-and their corresponding URLs:
+If you create a folder within the content folder (e.g. `content-sample/sub`) and put an `index.md` inside it, you can access that folder at the URL `http://example.com/?sub`. If you want another page within the sub folder, simply create a text file with the corresponding name and you will be able to access it (e.g. `content-sample/sub/page.md` is accessible from the URL `http://example.com/?sub/page`). Below we've shown some examples of locations and their corresponding URLs:
 
 <table style="width: 100%; max-width: 40em;">
     <thead>
@@ -53,16 +44,15 @@ and their corresponding URLs:
     </tbody>
 </table>
 
-If a file cannot be found, the file `content-sample/404.md` will be shown. You
-can add `404.md` files to any directory, so if you want to use a special error
-page for your blog, simply create `content-sample/blog/404.md`.
+If a file cannot be found, the file `content-sample/404.md` will be shown. You can add `404.md` files to any directory, so if you want to use a special error page for your blog, simply create `content-sample/blog/404.md`.
+
+Instead of adding your own contents to the `content-sample` folder, you should create your own `content` directory in Picos root directory. You can then add and access your contents as described above.
 
 ### Text File Markup
 
-Text files are marked up using [Markdown](https://daringfireball.net/projects/markdown/). They can also contain regular HTML.
+Text files are marked up using [Markdown][]. They can also contain regular HTML.
 
-At the top of text files you can place a block comment and specify certain
-attributes of the page. For example:
+At the top of text files you can place a block comment and specify certain attributes of the page. For example:
 
 <pre><code>---
 Title: Welcome
@@ -73,44 +63,29 @@ Robots: noindex,nofollow
 Template: index
 ---</code></pre>
 
-These values will be contained in the `{% raw %}{{ meta }}{% endraw %}` variable
-in themes (see below).
+These values will be contained in the `{% raw %}{{ meta }}{% endraw %}` variable in themes (see below).
 
 There are also certain variables that you can use in your text files:
 
-* <code>&#37;site_title&#37;</code> - The title of your Pico site
-* <code>&#37;base_url&#37;</code> - The URL to your Pico site; internal links
-  can be specified using <code>&#37;base_url&#37;?sub/page</code>
-* <code>&#37;theme_url&#37;</code> - The URL to the currently used theme
-* <code>&#37;meta.*&#37;</code> - Access any meta variable of the current page,
-  e.g. <code>&#37;meta.author&#37;</code> is replaced with `Joe Bloggs`
+* `%site_title%` - The title of your Pico site
+* `%base_url%` - The URL to your Pico site; internal links can be specified using `%base_url%?sub/page`
+* `%theme_url%` - The URL to the currently used theme
+* `%meta.*%` - Access any meta variable of the current page, e.g. `%meta.author%` is replaced with `Joe Bloggs`
 
 ### Blogging
 
-Pico is not blogging software - but makes it very easy for you to use it as a
-blog. You can find many plugins out there implementing typical blogging
-features like authentication, tagging, pagination and social plugins. See the
-below Plugins section for details.
+Pico is not blogging software - but makes it very easy for you to use it as a blog. You can find many plugins out there implementing typical blogging features like authentication, tagging, pagination and social plugins. See the below Plugins section for details.
 
-If you want to use Pico as a blogging software, you probably want to do
-something like the following:
+If you want to use Pico as a blogging software, you probably want to do something like the following:
 <ol>
     <li>
-        Put all your blog articles in a separate <code>blog</code> folder in your <code>content</code>
-        directory. All these articles should have both a <code>Date</code> and <code>Template</code> meta
-        header, the latter with e.g. <code>blog-post</code> as value (see Step 2).
+        Put all your blog articles in a separate <code>blog</code> folder in your <code>content</code> directory. All these articles should have both a <code>Date</code> and <code>Template</code> meta header, the latter with e.g. <code>blog-post</code> as value (see Step 2).
     </li>
     <li>
-        Create a new Twig template called <code>blog-post.twig</code> (this must match the
-        <code>Template</code> meta header from Step 1) in your theme directory. This template
-        probably isn't very different from your default <code>index.twig</code>, it specifies
-        how your article pages will look like.
+        Create a new Twig template called <code>blog-post.twig</code> (this must match the <code>Template</code> meta header from Step 1) in your theme directory. This template probably isn't very different from your default <code>index.twig</code>, it specifies ow your article pages will look like.
     </li>
     <li>
-        Create a <code>blog.md</code> in your <code>content</code> folder and set its <code>Template</code> meta
-        header to e.g. <code>blog</code>. Also create a <code>blog.twig</code> in your theme directory.
-        This template will show a list of your articles, so you probably want to
-        do something like this:
+        Create a <code>blog.md</code> in your <code>content</code> folder and set its <code>Template</code> meta header to e.g. <code>blog</code>. Also create a <code>blog.twig</code> in your theme directory. This template will show a list of your articles, so you probably want to do something like this:
 
         {% raw %}<pre><code>{% for page in pages %}
     {% if page.id starts with &quot;blog/&quot; %}
@@ -123,17 +98,11 @@ something like the following:
 {% endfor %}</code></pre>{% endraw %}
     </li>
     <li>
-        Let Pico sort pages by date by setting <code>$config['pages_order_by'] = 'date';</code>
-        in your <code>config/config.php</code>. To use a descending order (newest articles
-        first), also add <code>$config['pages_order'] = 'desc';</code>. The former won't affect
-        pages without a <code>Date</code> meta header, but the latter does. To use ascending
-        order for your page navigation again, add Twigs <code>reverse</code> filter to the
-        navigation loop (<code>{&#37; for page in pages|reverse &#37;}...{&#37; endfor &#37;}}</code>)
-        in your themes <code>index.twig</code>.
+        Let Pico sort pages by date by setting <code>$config['pages_order_by'] = 'date';</code> in your <code>config/config.php</code>. To use a descending order (newest articles first), also add <code>$config['pages_order'] = 'desc';</code>. The former won't affect pages without a <code>Date</code> meta header, but the latter does. To use ascending order for your page navigation again, add Twigs <code>reverse</code> filter to the navigation loop (<code>{&#37; for page in pages|reverse &#37;}...{&#37; endfor &#37;}}</code>) in your themes <code>index.twig</code>.
     </li>
     <li>
-        Make sure to exclude the blog articles from your page navigation. You can
-        achieve this by adding <code>{&#37; if not page starts with "blog/" &#37;}...{&#37; endif &#37;}</code>
-        to the navigation loop.
+        Make sure to exclude the blog articles from your page navigation. You can achieve this by adding <code>{&#37; if not page starts with "blog/" &#37;}...{&#37; endif &#37;}</code> to the navigation loop.
     </li>
 </ol>
+
+[Markdown]: http://daringfireball.net/projects/markdown/syntax

_docs/customization.md

@@ -4,40 +4,24 @@ toc:
         _title: Customization
         themes: Themes
         plugins: Plugins
-nav: 3
+nav: 5
 ---
 
 ## Customization
 
-Pico is highly customizable in two different ways: On the one hand you can
-change Picos appearance by using themes, on the other hand you can add new
-functionality by using plugins. Doing the former includes changing Picos HTML,
-CSS and JavaScript, the latter mostly consists of PHP programming.
+Pico is highly customizable in two different ways: On the one hand you can change Picos appearance by using themes, on the other hand you can add new functionality by using plugins. Doing the former includes changing Picos HTML, CSS and JavaScript, the latter mostly consists of PHP programming.
 
-This is all Greek to you? Don't worry, you don't have to spend time on these
-techie talk - it's very easy to use one of the great themes or plugins others
-developed and released to the public. Please refer to the next sections for
-details.
+This is all Greek to you? Don't worry, you don't have to spend time on these techie talk - it's very easy to use one of the great themes or plugins others developed and released to the public. Please refer to the next sections for details.
 
 ### Themes
 
-You can create themes for your Pico installation in the `themes` folder. Check
-out the default theme for an example. Pico uses [Twig](http://twig.sensiolabs.org/documentation) for template
-rendering. You can select your theme by setting the `$config['theme']` option
-in `config/config.php` to the name of your theme folder.
+You can create themes for your Pico installation in the `themes` folder. Check out the default theme for an example. Pico uses [Twig][] for template rendering. You can select your theme by setting the `$config['theme']` option in `config/config.php` to the name of your theme folder.
 
-All themes must include an `index.twig` (or `index.html`) file to define the
-HTML structure of the theme. Below are the Twig variables that are available
-to use in your theme. Please note that paths (e.g. `{% raw %}{{ base_dir }}{% endraw %}`) and URLs
-(e.g. `{% raw %}{{ base_url }}{% endraw %}`) don't have a trailing slash.
+All themes must include an `index.twig` (or `index.html`) file to define the HTML structure of the theme. Below are the Twig variables that are available to use in your theme. Please note that paths (e.g. `{% raw %}{{ base_dir }}{% endraw %}`) and URLs (e.g. `{% raw %}{{ base_url }}{% endraw %}`) don't have a trailing slash.
 
-* `{% raw %}{{ config }}{% endraw %}` - Contains the values you set in `config/config.php`
-                   (e.g. `{% raw %}{{ config.theme }}{% endraw %}` becomes `default`)
+* `{% raw %}{{ config }}{% endraw %}` - Contains the values you set in `config/config.php` (e.g. `{% raw %}{{ config.theme }}{% endraw %}` becomes `default`)
 * `{% raw %}{{ base_dir }}{% endraw %}` - The path to your Pico root directory
-* `{% raw %}{{ base_url }}{% endraw %}` - The URL to your Pico site; use Twigs `link` filter to
-                     specify internal links (e.g. `{% raw %}{{ "sub/page"|link }}{% endraw %}`),
-                     this guarantees that your link works whether URL rewriting
-                     is enabled or not
+* `{% raw %}{{ base_url }}{% endraw %}` - The URL to your Pico site; use Twigs `link` filter to pecify internal links (e.g. `{% raw %}{{ "sub/page"|link }}{% endraw %}`), this guarantees that your link works whether URL rewriting is enabled or not
 * `{% raw %}{{ theme_dir }}{% endraw %}` - The path to the currently active theme
 * `{% raw %}{{ theme_url }}{% endraw %}` - The URL to the currently active theme
 * `{% raw %}{{ rewrite_url }}{% endraw %}` - A boolean flag indicating enabled/disabled URL rewriting
@@ -51,8 +35,7 @@ to use in your theme. Please note that paths (e.g. `{% raw %}{{ base_dir }}{% en
     * `{% raw %}{{ meta.time }}{% endraw %}`
     * `{% raw %}{{ meta.robots }}{% endraw %}`
     * ...
-* `{% raw %}{{ content }}{% endraw %}` - The content of the current page
-                    (after it has been processed through Markdown)
+* `{% raw %}{{ content }}{% endraw %}` - The content of the current page after it has been processed through Markdown)
 * `{% raw %}{{ pages }}{% endraw %}` - A collection of all the content pages in your site
     * `{% raw %}{{ page.id }}{% endraw %}` - The relative path to the content file
     * `{% raw %}{{ page.url }}{% endraw %}` - The URL to the page
@@ -77,40 +60,27 @@ Pages can be used like the following:
     {% endfor %}
 &lt;/ul&gt;</code></pre>{% endraw %}
 
-You can use different templates for different content files by specifying the
-`Template` meta header. Simply add e.g. `Template: blog-post` to a content file
-and Pico will use the `blog-post.twig` file in your theme folder to render
-the page.
+You can use different templates for different content files by specifying the `Template` meta header. Simply add e.g. `Template: blog-post` to a content file and Pico will use the `blog-post.twig` file in your theme folder to render the page.
 
-You don't have to create your own theme if Picos default theme isn't sufficient
-for you, you can use one of the great themes third-party developers and
-designers created in the past. As with plugins, you can find themes in
-[our Wiki](https://github.com/picocms/Pico/wiki/Pico-Themes).
+You don't have to create your own theme if Picos default theme isn't sufficient for you, you can use one of the great themes third-party developers and designers created in the past. As with plugins, you can find themes in [our Wiki][WikiThemes].
 
 ### Plugins
 
 #### Plugins for users
 
-Officially tested plugins can be found at [http://picocms.com/plugins]({{ site.base_url }}/plugins.html),
-but there are many awesome third-party plugins out there! A good start point
-for discovery is [our Wiki](https://github.com/picocms/Pico/wiki/Pico-Plugins).
+Officially tested plugins can be found at [http://picocms.org/plugins.html][OfficialPlugins], but there are many awesome third-party plugins out there! A good start point for discovery is [our Wiki][WikiPlugins].
 
-Pico makes it very easy for you to add new features to your website. Simply
-upload the files of the plugin to the `plugins/` directory and you're done.
-Depending on the plugin you've installed, you may have to go through some more
-steps (e.g. specifying config variables), the plugin docs or `README` file will
-explain what to do.
+Pico makes it very easy for you to add new features to your website. Simply upload the files of the plugin to the `plugins/` directory and you're done. Depending on the plugin you've installed, you may have to go through some more steps (e.g. specifying config variables), the plugin docs or `README` file will explain what to do.
 
-Plugins which were written to work with Pico 1.0 can be enabled and disabled
-through your `config/config.php`. If you want to e.g. disable the [PicoExcerpt](https://github.com/picocms/Pico/blob/master/plugins/02-PicoExcerpt.php)
-plugin, add the following line to your `config/config.php`:
-`$config['PicoExcerpt.enabled'] = false;`. To force the plugin to be enabled
-replace `false` with `true`.
+Plugins which were written to work with Pico 1.0 can be enabled and disabled through your `config/config.php`. If you want to e.g. disable the `PicoExcerpt` plugin, add the following line to your `config/config.php`: `$config['PicoExcerpt.enabled'] = false;`. To force the plugin to be enabled replace `false` with `true`.
 
 #### Plugins for developers
 
-You're a plugin developer? We love you guys! You can find tons of information
-about how to develop plugins at [http://picocms.org/plugin-dev.html]({{ site.base_url }}/plugin-dev.html). If you'd
-developed a plugin for Pico 0.9 and older, you probably want to upgrade it
-to the brand new plugin system introduced with Pico 1.0. Please refer to the
-[Upgrade section of the docs]({{ site.base_url }}/plugin-dev.html#migrating-from-0x-to-10).
+You're a plugin developer? We love you guys! You can find tons of information about how to develop plugins at [http://picocms.org/plugin-dev.html][PluginDev]. If you'd developed a plugin for Pico 0.9 and older, you probably want to upgrade it to the brand new plugin system introduced with Pico 1.0. Please refer to the [upgrade section of the docs][PluginUpgrade].
+
+[Twig]: http://twig.sensiolabs.org/documentation
+[WikiThemes]: https://github.com/picocms/Pico/wiki/Pico-Themes
+[WikiPlugins]: https://github.com/picocms/Pico/wiki/Pico-Plugins
+[OfficialPlugins]: {{ site.base_url }}/plugins.html
+[PluginDev]: {{ site.base_url }}/plugin-dev.html
+[PluginUpgrade]: {{ site.base_url }}/plugin-dev.html#upgrade

_docs/getting-help.md

@@ -0,0 +1,33 @@
+---
+toc:
+    getting-help:
+        _title: Getting Help
+        getting-help-as-a-user: ... for users
+        getting-help-as-a-developer: ... for developers
+        you-still-need-help-or-experience-a-problem-with-pico: ... if all else fails
+nav: 7
+---
+
+## Getting Help
+
+### Getting Help as a user
+If you want to get started using Pico, please refer to the [user docs][HelpUserDocs] (you're reading them right now!). Please read the [upgrade notes][HelpUpgrade] if you want to upgrade from Pico 0.8 or 0.9 to Pico 1.0. You can find officially supported plugins and themes on [our website][OfficialPlugins]. A greater choice of third-party plugins and themes can be found in our [Wiki][] on the [plugins][WikiPlugins] or [themes page][WikiThemes] respectively. If you want to create your own plugin or theme, please refer to the ["Getting Help as a developer" section](#getting-help-as-a-developer) below.
+
+### Getting Help as a developer
+If you're a developer, please refer to the ["Contribute" section](#contribute) below and our [contribution guidelines][ContributionGuidelines]. To get you started with creating a plugin or theme, please read the [dev docs on our website][HelpDevDocs].
+
+### You still need help or experience a problem with Pico?
+When the docs can't answer your question or when you're experiencing problems with Pico, please don't hesitate to create a new [Issue][Issues] on GitHub. Concerning problems with plugins or themes, please refer to the website of the developer of this plugin or theme.
+
+Before creating a new Issue, please make sure the problem wasn't reported yet using [GitHubs search engine][IssuesSearch]. Please describe your issue as clear as possible and always include steps to reproduce the problem.
+
+[HelpUpgrade]: http://picocms.org/upgrade.html
+[HelpUserDocs]: http://picocms.org/docs.html
+[HelpDevDocs]: http://picocms.org/plugin-dev.html
+[OfficialPlugins]: http://picocms.org/plugins.html
+[Wiki]: https://github.com/picocms/Pico/wiki
+[WikiPlugins]: https://github.com/picocms/Pico/wiki/Pico-Plugins
+[WikiThemes]: https://github.com/picocms/Pico/wiki/Pico-Themes
+[Issues]: https://github.com/picocms/Pico/issues
+[IssuesSearch]: https://github.com/picocms/Pico/search?type=Issues
+[ContributionGuidelines]: https://github.com/picocms/Pico/blob/master/CONTRIBUTING.md

_docs/install.md

@@ -4,13 +4,12 @@ toc:
         _title: Install
         using-a-pre-bundled-release: Using a pre-bundled released
         composer: Composer
-    run: Run
 nav: 1
 ---
 
 ## Install
 
-You can install Pico either using a pre-bundled release or with composer. Pico requires PHP 5.3+
+You can install Pico either using a pre-bundled release or with composer. Pico is also available on [Packagist.org][] and may be included in other projects via `composer require picocms/pico`. Pico requires PHP 5.3+
 
 ### Using a pre-bundled release
 
@@ -27,32 +26,9 @@ Open a shell and navigate to the desired install directory of Pico within the `h
 Please note that this gives you the current development version of Pico, what is likely *unstable* and *not ready for production use*!
 
 #### Step 2
-Download [composer][composer] and run it with the `install` option:
+Download [composer][] and run it with the `install` option:
 <pre><code>$ curl -sS https://getcomposer.org/installer | php
 $ php composer.phar install</code></pre>
 
-Pico is available on [Packagist.org](http://packagist.org/packages/picocms/pico) and may be included in other projects via `composer require picocms/pico`
-
----
-
-## Run
-
-You have nothing to consider specially, simply navigate to your Pico install using your favorite web browser. Picos default contents will explain how to use your brand new, stupidly simple, blazing fast, flat file CMS.
-
-### You don't have a web server?
-
-Starting with PHP 5.4 the easiest way to try Pico is using [the built-in web server of PHP][PHPServer]. Please note that PHPs built-in web server is for development and testing purposes only!
-
-#### Step 1
-Navigate to Picos installation directory using a shell.
-
-#### Step 2
-Start PHPs built-in web server:
-<pre><code>$ php -S 127.0.0.1:8080</code></pre>
-
-#### Step 3
-Access Pico from <http://localhost:8080>.
-
 [LatestRelease]: https://github.com/picocms/Pico/releases/latest
 [composer]: https://getcomposer.org/
-[PHPServer]: http://php.net/manual/en/features.commandline.webserver.php

_docs/run.md

@@ -0,0 +1,24 @@
+---
+toc:
+    run: Run
+nav: 3
+---
+
+## Run
+
+You have nothing to consider specially, simply navigate to your Pico install using your favorite web browser. Picos default contents will explain how to use your brand new, stupidly simple, blazing fast, flat file CMS.
+
+### You don't have a web server?
+Starting with PHP 5.4 the easiest way to try Pico is using [the built-in web server of PHP][PHPServer]. Please note that PHPs built-in web server is for development and testing purposes only!
+
+#### Step 1
+Navigate to Picos installation directory using a shell.
+
+#### Step 2
+Start PHPs built-in web server:
+<pre><code>$ php -S 127.0.0.1:8080</code></pre>
+
+#### Step 3
+Access Pico from http://localhost:8080.
+
+[PHPServer]: http://php.net/manual/en/features.commandline.webserver.php

_docs/upgrade.md

@@ -1,12 +1,21 @@
 ---
 toc:
     upgrade: Upgrade
-nav: 5
+nav: 2
 ---
 
 ## Upgrade
 
-**ToDo:** Very short description about how to upgrade
+Upgrading Pico is very easy: You just have to replace all of Picos files - that's it! Nevertheless you should *always* create a backup of your Pico installation before upgrading.
 
-For more information about what has changed with Pico 1.0 and a step-by-step
-upgrade tutorial, please refer to the [upgrade page]({{ site.base_url}}/upgrade.html).
+Pico follows [Semantic Versioning 2.0][SemVer] and uses version numbers like `MAJOR`.`MINOR`.`PATCH`. When we update...
+
+- the `PATCH` version (e.g. `1.0.0` to `1.0.1`), we made backwards-compatible bug fixes. It's then sufficient to extract [Picos latest release][LatestRelease] to your existing installation directory and overwriting all files.
+- the `MINOR` version (e.g. `1.0` to `1.1`), we added functionality in a backwards-compatible manner, but anyway recommend you to "install" Pico newly. Backup all of your files, empty your installation directory and install Pico as elucidated above. You can then copy your `config/config.php` and `content` directory without any change. If applicable, you can also copy the folder of your custom theme within the `themes` directory. Provided that you're using plugins, also copy all of your plugins from the `plugins` directory.
+- the `MAJOR` version (e.g. `1.0` to `2.0`), a appropriate upgrade tutorial will be provided.
+
+Upgrading Pico 0.8 or 0.9 to Pico 1.0 is a special case. The new `PicoDeprecated` plugin ensures backwards compatibility, so you basically can follow the above upgrade instructions as if we updated the `MINOR` version. However, we recommend you to take some further steps to confine the neccessity of `PicoDeprecated` as far as possible. For more information about what has changed with Pico 1.0 and a step-by-step upgrade tutorial, please refer to the [upgrade page of our website][HelpUpgrade].
+
+[SemVer]: http://semver.org
+[LatestRelease]: https://github.com/picocms/Pico/releases/latest
+[HelpUpgrade]: {{ site.base_url }}/upgrade.html