Update docs on creating comparison pages

[ci skip]

README.md

@@ -319,27 +319,109 @@ follow the steps below:
 The feature page grabs its content automatically from the file
 `/data/features.yml`.
-### Update the comparison page (under `/comparison`)
-The comparison page grabs its content automatically from the file
-`/data/comparisons.yml`.
-When adding a new comparison, make sure that you follow the structure below:
+### Create or update the comparison pages (under `/comparison`)
+The [comparison page][comp] grabs its content automatically from the files under
+`data/comparisons/`.
+There are 3 files in total which you need to create or edit:
+- `data/comparisons/gitlab_vs_competitor.yml`: Create for new comparisons. Every
+  comparison page has its own yaml file. **Use underscores**
+- `source/comparison/gitlab-vs-competitor.html.haml`: Create for new comparisons.
+  Every comparison page has its own html file. **Use dashes**
+- `source/includes/comparison_table.html.haml`: Edit for new or existing
+  comparisons.
+
+---
+
+**Step 1**
+
+Add a new yaml file named after the comparison using underscores:
+`data/comparisons/gitlab_vs_competitor.yml`. You can start by copying an
+existing one and then changing its content. Yaml files are sensitive to
+indentation, so be extra careful. Make sure that you follow the structure below:
+
+```yaml
+title: "Competitor vs GitLab"
+pdf: gitlab-vs-competitor.pdf
+competitor_one:
+  name: 'GitLab'
+  logo: '/images/comparison/gitlab-logo.svg'
+competitor_two:
+  name: 'Competitor'
+  logo: '/images/comparison/competitor-logo.svg'
+last_updated: 'May 5, 2017'
+features:
+  - title: "Briefly explain the feature"
+    description: |
+      Describe the differences in detail. This text can span in multiple
+      lines without interfering with its structure. It will always appear
+      as one paragraph.
+    link_description: "Learn more about Feature Name."
+    link: "link to GitLab's feature page documentation or blog post"
+    competitor_one: true
+    competitor_two: true
 ```
-- title: ""
-  description: ""
-  link_description: ""
-  link:
-  competitor_one: true
-  competitor_two: false
+
+Notes:
+
+- Although the file is named with GitLab being first, the title should have the
+  competitor name first.
+- The `pdf` name should be similar to the yaml file name, but with dashes. In
+  short, it has to match the HTML page name in step 2.
+- Remember to update the date every time you make a change.
+- The competitor's logo (`competitor_two`) can be `svg` or `png`. Save it in
+  `source/images/comparison/competitor-logo.svg`.
+- In the features area, `competitor_one` is always GitLab, and `competitor_two`
+  is the competitor we are compared against. Values for these two fields are
+  `true|false|sortof`.
+
+**Step 2**
+
+Add a new haml file named after the comparison using dashes:
+`source/comparison/gitlab-vs-competitor.html.haml`. You can start by copying an
+existing one and then editing it. The only change you need to make is the
+name of the yaml file you created above:
+
+```yaml
+---
+layout: comparison_page
+trial_bar: true
+title: GitLab compared to other tools
+suppress_header: true
+image_title: '/images/comparison/title_image.png'
+extra_css:
+  - compared.css
+extra_js:
+  - comparison.js
+---
+
+- data.comparisons.gitlab_vs_competitor do |comparison_block|
+  = partial "includes/comparison_table", locals: { comparison_block: comparison_block }
+```
+
+**Step 3**
+
+As a last step, you need to add the new page in the dropdown menu. To do that,
+open `source/includes/comparison_table.html.haml` and add an entry of your newly
+added comparison page. Again, you can copy one of the entries you'll find inside
+and just change its content. Haml files are sensitive to indentation, so be
+extra careful:
+
+```haml
+%li
+  = highlight_active_nav_link("Competitor vs. GitLab", "/comparison/gitlab-vs-competitor.html#dropdown")
 ```
-Title and description fields are mandatory.
-`competitor_one` is always GitLab,
-`competitor_two` is the competitor we are compared against. Values for these two
-fields are `true|false|sortof`.
+**Step 4**
+If you followed the above 3 steps, the new comparison page should be reachable
+under `/comparison/gitlab-vs-competitor.html` and you should see it in the
+dropdown menu. The last thing you need to do is create the PDF. Follow the
+info in [creating comparison PDFs](#comparison-pdfs).
+
+[comp]: https://about.gitlab.com/comparison/
 ### Update the release list page (under `/release-list`)
@@ -447,15 +529,34 @@ derived from a corresponding 'printable' HTML file, such as
 The PDF files are generated by [pandoc](http://pandoc.org/) using
 [LaTeX/XeTeX](http://xetex.sourceforge.net/). Global PDF parameters such
-as page margins are configured in pdf_template.tex.
+as page margins are configured in `pdf_template.tex`.
 ### Install PDF dependencies
-On OS X: run `brew install pandoc` and install [Basic
-TeX](https://tug.org/mactex/morepackages.html).
-For the comparison PDFs you will need to run the following on OS X:
-`brew cask install wkhtmltopdf`
+There are two kinds of PDFs created: the comparison pages ones and all the others.
+---
+
+For the comparison PDFs you will need to install [wkhtmltopdf].
+
+On macOS:
+
+```
+brew cask install wkhtmltopdf
+```
+
+---
+
+For all the others you need [pandoc](http://pandoc.org/installing.html). On
+macOS run:
+
+```
+brew install pandoc
+```
+
+Then, install [Basic TeX](https://tug.org/mactex/morepackages.html).
+
+[wkhtmltopdf]: https://wkhtmltopdf.org/downloads.html
 ### PDF development
@@ -500,18 +601,27 @@ website, you have to:
 ### Comparison PDFs
+>**Notes:**
+- Before creating the PDF for a new comparison page, you need to have
+  [created the page](#create-or-update-the-comparison-pages-under-comparison)
+  beforehand.
+- Make sure you have all [PDF dependencies installed]()#install-pdf-dependencies.
+
 The comparison PDFs are generated in a slightly different way and require a
 different command to be run. Before the PDFs can be generated the website
 needs to be built locally by running the following:
-`bundle exec middleman build`
+```
+bundle exec middleman build
+```
 After running that you can now run the following to generate the PDFs:
-`bundle exec rake comparison_pdfs`
-Once you have done that you are free to commit and push these to GitLab.com
-to then be merged into master.
+```
+bundle exec rake comparison_pdfs
+```
+Once you have done that you are free to commit and push these to GitLab.com.
 ## Custom Generators
@@ -581,4 +691,4 @@ In case someone forgot the most important commands and is catting this file from
 ```
 bundle exec rake new_post
 bundle exec middleman
-```
\ No newline at end of file
+```

comparison_pdfs.sh

@@ -6,5 +6,5 @@ for filename in public/comparison/pdfs/*.html; do
   wkhtmltopdf --margin-left 0 --margin-right 0 --margin-top 0 --zoom 3 $filename $pdffilename
-  echo "✅  PDF pdffilename generated!"
+  echo "✅  PDF $pdffilename generated!"
 done