add guidelines to readme

README.md

@@ -15,9 +15,6 @@ MkDocs documentation for the [CMS Open Data Guide](https://cms-opendata-guide.we
 ## The Guide's philosophy
 The main purpose of the CMS Open Data Guide is to facilitate the understanding of the CMS open data, its tools, and their usage for research. 
 
-The Guide is meant to organize pieces of information already available in the [CMS CERN Open Portal](http://opendata.cern.ch/search?experiment=CMS) site, the public [CMS Twiki](https://twiki.cern.ch/twiki/bin/view/CMSPublic/WebHome), the [CMSSW](http://cms-sw.github.io/) components, etc., in a logical way, following mainly the structure of a real physics analysis project.
-
-Therefore, the sections at the heart of this Guide should also point to practical lessons or exercises that are implemented in the sister [cms-opendata-workshop](https://github.com/cms-opendata-workshop) organization.
 
 ## How to contribute
 
@@ -29,7 +26,8 @@ Everyone is welcome to help build and/or improve this guide. If you find a bug o
 1. Check whether the topic, corresponding to the issue, 
     has already a page in the file that steers the [structure of the guide](https://github.com/cernopendata/cms-opendata-guide/blob/master/mkdocs.yml).   
 1. If there is no such a page, contact one of the coordinators of the project to create it for you or to agree to create it yourself.  You could just make a comment in your issue, tagging a coordinator therein, which will trigger the discussion.
-1. Once the appropiate page exists, you can start writing the relevant information either directly into the repository on the webpage or (preferably) on your own, local github area.  
+1. Once the appropiate page exists, you can start writing the relevant information either directly into the repository on the webpage or (preferably) on your own, local github area.
+   * **Please follow the [content guidelines](#content-guidelines)** below.
    * If working locally, feel free to test it first following the [local testing](#test-locally) instructions below.
    * Make sure to check for missing new lines at EOF and trailing white spaces.  A simple way to check is by using the `git diff` and/or `git diff --check` commands.
    * Please test locally for style issues by running the command `./run-tests.sh --check-docstyle` (Note that you might need to install [awesome_bot](https://github.com/cernopendata/cms-opendata-guide/blob/eedc8d880729c3ef69ea75c1ea38efa6216a1537/.github/workflows/ci.yml#L41))
@@ -42,6 +40,18 @@ Everyone is welcome to help build and/or improve this guide. If you find a bug o
 
 Make a direct [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) or (preferably) [contact us][email] first.
 
+## Content guidelines
+
+Please follow these simple guidelines:
+
+* The Guide is meant to organize pieces of information already available in the [CMS CERN Open Portal](http://opendata.cern.ch/search?experiment=CMS) site, the public [CMS Twiki](https://twiki.cern.ch/twiki/bin/view/CMSPublic/WebHome), the [CMSSW](http://cms-sw.github.io/) components, etc., in a logical way, following mainly the structure of a real physics analysis project.
+* Check out the [basics for markdown](https://squidfunk.github.io/mkdocs-material/reference/). 
+* **Do not** paste big code snippets into the Guide pages.
+* If there is need to point to extended lines of code it is best to direct the user to the practical lessons or exercises that are implemented in the sister [cms-opendata-workshop](https://github.com/cms-opendata-workshop) organization using web links.
+* The Guide **is not** supposed to be a copy of these tutorials (workshop) pages but rather an aid to navigate them.
+* If differentiation between `Run 1` and `Run 2` information is required, please use [material mkdocs tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#grouping-other-content) for grouping content.
+* If you need an example of how the content is written, check out one of the already-written pages in the [docs](https://github.com/cernopendata/cms-opendata-guide/tree/master/docs) folder of this repository; [this one](https://raw.githubusercontent.com/cernopendata/cms-opendata-guide/master/docs/tools/docker.md), for instance.
+
 
 ## Test locally
 
@@ -75,7 +85,7 @@ $ firefox http://127.0.0.1:8000
 ```
 You can exit from the virtual environment with `deactivate`.
 
-You can run local tests executing `./run-tests.sh`. Testing requires [a ruby installation](https://www.ruby-lang.org/en/documentation/installation/). You will also need to install the ruby gem `awesome_bot` by issuing `gem install awesome_bot` and make sure that gem in accessible on your path.  In addition, `npx` is also required by the test script.  For this one should install `nodejs` and `npm`, and install it using the node package manager (npm) as `npm i npx`.
+You can run local tests executing `./run-tests.sh`. Testing requires [a ruby installation](https://www.ruby-lang.org/en/documentation/installation/). You will also need to install the ruby gem `awesome_bot` by issuing `gem install awesome_bot` and make sure that gem in accessible on your path.  In addition, `npx` is also required by the test script.  For this one should install `nodejs` and `npm`, and install it using the node package manager (npm) as `npm i npx`.   
 
 ### Note on markdown