Contribution guide and frontpage update

* Adds contribution guide. (closes openaire#5)

* Removes "guidelines in practice" section. (addresses openaire#20)

* Revises front page. (addresses openaire#17)

* Removes reference to old wiki page. (closes openaire#12)

CONTRIBUTING.rst

@@ -1,17 +1,59 @@
 Contributing
 ============
 
-Initial stub for contribution guidelines.
-
-* Create a GitHub account
-* Ask a question
-* Editing the text via GitHub.
-* ReStructuredText syntax and cheat sheet.
-* Submitting a pull request.
-  - commit message
-  - purpose
-* Discussing the pull request.
-  - updating the pull request.
-  - emoji
-  - notification @mention
-*Merging the pull request.
+The OpenAIRE guidelines can be viewed online on http://guidelines.openaire.eu.
+
+Create a GitHub account
+-----------------------
+You will need a GitHub account to contribute to the OpenAIRE guidelines. It is
+free an easy - just go to https://github.com/join and follow the instructions.
+
+Once you've got your GitHub account, ahead on over to the OpenAIRE Guidelines
+on GitHub https://github.com/openaire/guidelines
+
+.. image:: images/join.png
+   :scale: 50%
+   :align: center
+
+Participate in the discussion
+-----------------------------
+* Want to participate in our discussion? Join the ongoing conversation on
+  our list of issues: https://github.com/openaire/guidelines/issues
+
+* Have a question, feedback or problem? Simply go open a new
+  issue on our GitHub repository:
+  https://github.com/openaire/guidelines/issues/new.
+
+You can also get to the "New issue" from the frontpage of our GitHub
+repository:
+
+.. image:: images/issues.png
+   :align: center
+   :scale: 100%
+
+**Styles**
+
+The description of issues can be styled using a syntax called Markdown. See
+more on how to create headings, bold and bullets on
+https://guides.github.com/features/mastering-markdown/. You can even include
+images in the text, simply by dragging and dropping the image onto the
+issue description text area.
+
+Editing the guidelines
+----------------------
+Found a typo or want to revise major parts of the guidelines? Editing the
+guidelines can be done directly on GitHub. If this is the first time you
+are using GitHub, follow our guide here: :ref:`contrib_editing`
+
+.. toctree::
+   :maxdepth: 1
+
+   contrib_editing
+
+
+Get notified
+------------
+Afraid you missed an update? GitHub allows you to easily keep updated with the
+latest changes using their notifications:
+
+* https://github.com/openaire/guidelines/notifications

README.rst

@@ -1,9 +1,15 @@
 OpenAIRE Guidelines
 ===================
-Welcome. The intention of this GitHub repository is to provide a public space to share OpenAIREs work on interoperability and to engage with the community.
+Welcome to the OpenAIRE Guidelines. The intention of this is to provide a public space to share OpenAIREs work on interoperability and to engage with the community. The OpenAIRE Guidelines helps repository managers expose publications, datasets and CRIS metadata via the OAI-PMH protocol in order to integrate with OpenAIRE infrastructure.
 
 Head over to http://guidelines.openaire.eu to read the guidelines.
 
+OpenAIRE Guidelines consists of three guidelines for publication repositories, data archives and CRIS systems respectively:
+
+- OpenAIRE Guidelines for Literature Repositories
+- OpenAIRE Guidelines for Data Archives
+- OpenAIRE Guidelines for CRIS Managers based on CERIF-XML
+
 Contribution Guidelines
 ~~~~~~~~~~~~~~~~~~~~~~~
 See CONTRIBUTING.rst

docs/contrib_editing.rst

@@ -0,0 +1,76 @@
+.. _contrib_editing:
+
+Editing the guidelines
+----------------------
+Found a typo or want to revise major parts of the guidelines? Editing the
+guidelines can be done directly on GitHub.
+
+1. Go to http://guidelines.openaire.eu and find the page you want to edit.
+
+2. Click "Edit on GitHub" in the top right corner. This will take you directly
+   to the source file on GitHub.
+
+   .. image:: images/editongithub.png
+      :align: center
+      :scale: 100%
+
+3. Click the edit icon. If it's grayed out, it's likely because you are not
+   signed into your GitHub account.
+
+   .. image:: images/editicon.png
+      :align: center
+      :scale: 100%
+
+4. Edit the file. Note that the editor supports full-screen mode and allows you
+   to preview your changes.
+
+   .. image:: images/editfile.png
+      :align: center
+      :scale: 100%
+
+5. Once your done editing the file, write a small commit message to
+   propose the file change and finally click "Propose file change". This will
+   allow you to create what is called a "pull request". See next section.
+
+
+Submitting a pull request
+-------------------------
+
+1. After clicking "Propose file change", you can review your changes compared
+   against the latest master version. If you're happy with the changes, go
+   a head and click "Create pull request".
+
+   .. image:: images/comparechanges.png
+      :align: center
+      :scale: 50%
+
+2. Enter a title for your pull request and describe the changes made if
+   necessary and finally click, "Create pull request".
+
+   .. image:: images/openpr.png
+      :align: center
+      :scale: 50%
+
+
+Discussing the pull request
+---------------------------
+
+1. Everyone can see your proposed changes, and the changes can be discussed.
+   Every pull request is also automatically checked for errors in the
+   documentation source files by an external service called TravisCI.
+
+   .. image:: images/pr.png
+         :align: center
+         :scale: 50%
+
+
+2. The tab "Files changed", others can see the changes to the files, and
+   comment on individual lines as well.
+
+
+Merging the pull request
+------------------------
+
+Once the changes have been approved, one of the editors will merge the changes
+into the master version. After the merge, the changes are automatically
+propagated to online version on http://guidelines.openaire.eu.

docs/contributing.rst

@@ -0,0 +1,3 @@
+.. _contributing:
+
+.. include:: ../CONTRIBUTING.rst

docs/index.rst

@@ -2,18 +2,12 @@
 OpenAIRE Guidelines
 ###################
 
-Welcome to the OpenAIRE Guidelines. The intention of this is to provide a public space to share OpenAIREs work on interoperability and to engage with the community. This means you are invited to comment and change the content of this wiki. Please login as a 'Guest' at the log in/create account page.
+.. image:: images/openaire.png
+   :align: right
 
-Compatibility with the EC-Horizon 2020 Open Access requirements
----------------------------------------------------------------
+Welcome to the OpenAIRE Guidelines. The intention of this is to provide a public space to share OpenAIREs work on interoperability and to engage with the community. The OpenAIRE Guidelines helps repository managers expose publications, datasets and CRIS metadata via the OAI-PMH protocol in order to integrate with OpenAIRE infrastructure.
 
-The European Commission has published `Guidelines on Open Access to Scientific Publications and Research Data <http://ec.europa.eu/research/participants/data/ref/h2020/grants_manual/hi/oa_pilot/h2020-hi-oa-pilot-guide_en.pdf>`_ (version 1.0, 11-Dec-2013).
-By following the :ref:`literature` it is ensured that specific requirements on bibliographic information about Open Access publications are met.
-
-These requirements are summarized here: :ref:`h2020`.
-
-OpenAIRE Guidelines for specific types of data sources
-------------------------------------------------------
+OpenAIRE Guidelines consists of three guidelines for publication repositories, data archives and CRIS systems respectively:
 
 .. toctree::
    :maxdepth: 1
@@ -22,18 +16,29 @@ OpenAIRE Guidelines for specific types of data sources
    data/index
    cris/index
 
+The guidelines specifically provide guidance on how to specify:
+
+- Access right
+- Funding information
+- Related publication and datasets.
+
+Participate
+-----------
+You are invited to participate by commenting or editing the content. See our guide for how to get started:
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing
 
 OpenAIRE Validator
 ------------------
-The OpenAIRE Validator service http://validator.openaire.eu allows to test compatibility of data source providers with the OpenAIRE Guidelines.
-It provides rule sets that allow to test usage of the OAI-PMH implementation of the data source provider and syntax / semantics of metadata fields according to the OpenAIRE Guidelines.
+The OpenAIRE Validator service http://validator.openaire.eu allows to test your repository's compatibility with the OpenAIRE Guidelines.
+
 If validation succeeds the data source can be registered for regular aggregation and indexing in OpenAIRE.
-OpenAIRE allows for registration institutional and thematic repositories registered in OpenDOAR, research data repositories registered in re3data, individual e-Journals, CRIS, aggregators and publishers.
+OpenAIRE allows for registration of institutional and thematic repositories registered in OpenDOAR, research data repositories registered in re3data, individual e-Journals, CRIS, aggregators and publishers.
 
-.. Guidelines in practice
-   ----------------------
-   These pages are all open and intended for all stakeholders and data providers to add their experiences and best practices. OpenAIRE colleagues will also add their experiences when new types of data providers engage with OpenAIRE.
+Horizon 2020 Open Access Requirements
+-------------------------------------
 
-   - For literature repository managers
-   - For data archive managers
-   - For CRIS Managers
+The European Commission has published `Guidelines on Open Access to Scientific Publications and Research Data <http://ec.europa.eu/research/participants/data/ref/h2020/grants_manual/hi/oa_pilot/h2020-hi-oa-pilot-guide_en.pdf>`_ (version 1.0, 11-Dec-2013). By following the :ref:`literature` it is ensured that specific requirements on bibliographic information about Open Access publications are met. These requirements are summarized here: :ref:`h2020`.