WIP GUI path for contributing instructions

CONTRIBUTING.md

@@ -25,11 +25,19 @@ CSC staff: do these two things _first_:
 2. Then [join here the CSC employees team](https://github.com/orgs/CSCfi/teams/employees/members). Membership
 gives you permissions to edit source files that build the user guide. (Wait for a confirmation email.)
 
-The rest of this document describes the workflow in Github as well as instructions for previewing and deploying the documentation. See [Style guide](STYLEGUIDE.md) for content and formatting instructions and [Frequently Asked Questions](FAQ.md) for more in depth explanations of common questions you might encounter while contributing.
+The rest of this document describes the workflow in Github as well as instructions for previewing and
+deploying the documentation. There are more resources available, though:
+
+- [STYLEGUIDE.md](STYLEGUIDE.md) — Content and formatting instructions
+- [FAQ.md](FAQ.md) — More in-depth explanations of common questions you might encounter while contributing
+- [GETTING_STARTED.md](GETTING_STARTED.md) — Setting up a local development environment
+- [Reference card](docs.csc.fi/ref) — On the available elements
+    - [Markdown source for Reference card](docs/ref.md)
 
 ## For the impatient
 
 Once you've completed the steps above:
+
 * In [docs.csc.fi](https://docs.csc.fi) go to the page you want to edit and click the pen icon at top right
 * (sign in to GitHub) and edit the content
 * Scroll down to commit changes (create a new branch) -> make a pull request
@@ -60,7 +68,7 @@ must use pull requests.
         - If your commits aren't showing up on the pull request, i.e., the pull request isn't updating when making new commits, try switching the base branch ('Edit' button, top-right) from `master` to something else and then back again.
     - Write meaningful pull request messages, so it is easier for reviewers to do their job.
     - Communicate! Use "WIP" (= Work In Progress) in your pull request title, if you don't wish the branch to be merged to master (i.e. you want to continue working with it).
- - Once your PR has been accepted, remove the temporary branch (if not deleted by an admin at merge)
+ - Once your PR has been accepted, remove the temporary branch (if not deleted automatically at merge)
 
 #### Reviewer
 
@@ -79,7 +87,7 @@ If you get a request to review a pull request, please contribute to help publish
 If you see an approved branch:
 
  - "Squash and merge" it
- - Delete the (now unnecessary) branch
+ - Delete the (now unnecessary) branch (if not deleted automatically at merge)
  - Occasionally the number of (unnecessary) branches grows: prune.
 
 **Note:** If you make bigger changes to the (main) categories / menu on the left, it might affect some links used on our webpages. Please communicate these changes, for example in the RC-channel #research.csc.fi.
@@ -141,7 +149,8 @@ git push origin your_branch_name
 ```
 
 Now, in the GitHub web GUI you can create a pull request, ask a person to review
-it and (some admin to) merge the changes. After the PR has been merged, the branch on github can be deleted.
+it and (some admin to) merge the changes. After the PR has been merged, the branch
+on GitHub should get deleted automatically (delete manually if not).
 
 **Tip 1.** Git uses [Vim](https://www.vim.org) as the default editor for commit
 messages. It is possible to change the default editor, but below are

FAQ.md

@@ -119,21 +119,22 @@ Common issues:
 Tests are run to check, for example, that your pull request complies with the CSC Docs style guide and that there are no broken links. If any such errors are found in your commits, the tests will not pass and you need to figure out what went wrong:
 
 1. Find out which tests did not pass under the notification `Some checks were not successful` in the Review-dialogue (marked with a red x and text `Failing after X - Build Failed`).
-2. To the right of the failed test, click `Details`, which opens the `Checks` tab.
-3. Under the `Build Failed` section, click the link at `The build failed` to open the Travis CI page with logged details on the build.
-4. Scan through the Job log for any text marked in red. These are errors that the test found, and the reason for them is written before the red text. 
-5. An example error is shown below. Here, the `link_check.py` test script was run to see whether any links were broken. The test found two broken section links and it tells you in which files and on which lines the errors are.
-
-```console
-$ python3 tests/python_link_tests/link_check.py
-The section link namd.md#batch-script-example-for-mahti in file docs/apps/namd.md on line 33 is broken
-The section link cp2k.md#example-batch-script-for-mahti-using-mixed-mpi-openmp-parallelization in file docs/apps/cp2k.md on line 81 is broken
-No broken file links found
-No hidden files found
-The command "python3 tests/python_link_tests/link_check.py" exited with 1.
-```
-
-6. Fix the errors, commit and push the revised files to the same branch and the tests should now pass.
+1. To the right of the failed test, click `Details`, which opens the `Checks` tab.
+1. Under the `Build Failed` section, click the link at `The build failed` to open the Travis CI page with logged details on the build.
+    - Alternatively, look for your PR in the [list of csc-user-guide pull requests at Travis CI](https://app.travis-ci.com/github/CSCfi/csc-user-guide/pull_requests).
+1. Scan through the Job log for any text marked in red. These are errors that the test found, and the reason for them is written before the red text.
+1. An example error is shown below. Here, the `link_check.py` test script was run to see whether any links were broken. The test found two broken section links and it tells you in which files and on which lines the errors are.
+
+    ```console
+    $ python3 tests/python_link_tests/link_check.py
+    The section link namd.md#batch-script-example-for-mahti in file docs/apps/namd.md on line 33 is broken
+    The section link cp2k.md#example-batch-script-for-mahti-using-mixed-mpi-openmp-parallelization in file docs/apps/cp2k.md on line 81 is broken
+    No broken file links found
+    No hidden files found
+    The command "python3 tests/python_link_tests/link_check.py" exited with 1.
+    ```
+
+1. Fix the errors, commit and push the revised files to the same branch and the tests should now pass.
 
 ## How can I preview my edits?
 
@@ -177,13 +178,21 @@ pip install -r requirements.txt
 
 #### Conda
 
-Detailed instructions for installing Conda on Windows are found [here](GETTING_STARTED.md#setting-up-a-development-environment-on-windows), but the gist of it, regardless of the operating system used, is to install [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/) and to use it to create the virtual environment. So, with Miniconda installed, an environment containing everything needed to run MkDocs can be created by running the command
+Detailed instructions for installing Conda on Windows are found [here](GETTING_STARTED.md#setting-up-a-development-environment-on-windows), but the gist of it, regardless of the operating system used, is to install [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/), use it to create a virtual environment to install the requirements in. So, with Miniconda installed, an environment to run MkDocs in can be created by running the command
 
 ```bash
-conda env create -f docs/support/tutorials/conda/conda-docs-env-freeze.yaml
+conda env create -f development/conda-docs-base-1.0.yaml
 ```
 
-Add a `--force` flag if you already have a Conda environment named `docs-env` (you got `CondaValueError: prefix already exists: [...]`) and want to overwrite it. Activate the new environment with
+Add a `--force` flag if you already have a Conda environment named `docs-env` (you got `CondaValueError: prefix already exists: [...]`) and want to overwrite it. The environment is now ready for installing the requirements.
+
+```bash
+conda run -n docs-env pip install -r requirements.txt
+```
+
+If you want to reinstall the dependencies, add a `--force-reinstall` flag to the Pip command.
+
+Activate the new environment with
 
 ```bash
 conda activate docs-env
@@ -213,7 +222,7 @@ You can also run the tests locally with
 bash tests/run_tests.sh
 ```
 
-The tests depend on the Conda environment, so remember to activate it before running them.
+The tests depend on the Conda environment, so remember to activate it before running them, or use `conda run -n docs-env bash tests/run_tests.sh`.
 
 #### Scripts