diff --git a/README.md b/README.md index ac8ac1da..b56d01e5 100644 --- a/README.md +++ b/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