Improve contributing guide

.prettierrc.toml

@@ -0,0 +1,5 @@
+# Configuration for prettier
+# https://prettier.io/docs/en/configuration.html
+proseWrap = "always"
+tabWidth = 2
+printWidth = 80

.travis.yml

@@ -12,12 +12,16 @@ before_install:
   - gem install mdl
   - npm install postcss-cli@7.1.2
   - npm install autoprefixer@9.0
+  - npm install --save-dev --save-exact prettier
 script:
   # Markdown linting
   # https://github.com/markdownlint/markdownlint
   # MD002: first level header is managed by hugo theme
   # MD024: several sections repeat the header name, may be reviewed later
   - mdl -s relaxed -s style.rb -r ~MD002,~MD024 content/
+  # Check files using prettier
+  # XXX disabled until we review all the content
+  # - prettier --check content/en README.md
   # building static content with hugo
   - ./binaries/linux64/hugo
 deploy:

CONTRIBUTING.md

@@ -1,121 +1,3 @@
 # Contributing
 
-Thank you for taking the time to contribute to this project.
-The maintainers greatly appreciate the interest of contributors and rely on
-continued engagement with the community to ensure that this project remains
-useful.
-We would like to take steps to put contributors in the best possible position
-to have their contributions accepted.
-Please take a few moments to read this short guide on how to contribute; bear
-in mind that contributions regarding how to best contribute are also welcome.
-
-## Feedback and Questions
-
-If you wish to discuss anything related to the project, please open an issue or
-start a topic on the [EGI Community Forum](https://community.egi.eu).
-The maintainers will sometimes move issues off of GitHub to the community forum
-if it is thought that longer, more open-ended discussion would be beneficial,
-including a wider community scope.
-
-## Contribution Process
-
-All contributions have to go through a review process, and contributions can be
-made in two ways:
-
-- for simple contribution you can contribute from your browser by clicking the
-  **pencil** `Edit this file` icon shown at the top of a page that you are
-  viewing (See [GitHub
-  documented](https://help.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository)).
-  You will be guided through the required steps.
-- for more complex contributions and when you want to preview and test changes
-  locally you should fork the repository as documented below in the **Using
-  git** section.
-
-### Contributing via a Pull Request
-
-Before proposing a contribution via pull request, ideally there is an open
-issue describing the need for your contribution (refer to this issue number
-when you submit the pull request). We have a 3 steps process for contributions.
-
-1. Fork the project if you have not, and commit changes to a git branch.
-   Documentation on building the documentation locally is available in the
-   [README.md](README.md)
-1. Create a GitHub Pull Request for your change, following the instructions
-   in the pull request template.
-1. Perform a [Code Review](#code-review-process) with the maintainers on the
-   pull request.
-
-### Pull Request Requirements
-
-1. **Explain your contribution in plain language.** To assist the maintainers
-   in understanding and appreciating your pull request, please use the
-   template to explain _why_ you are making this contribution, rather than
-   just _what_ the contribution entails.
-
-### Code Review Process
-
-Code review takes place in GitHub pull requests. See [this
-article](https://help.github.com/articles/about-pull-requests/) if you're not
-familiar with GitHub Pull Requests.
-
-Once you open a pull request, maintainers will review your code using the
-built-in code review process in Github PRs. The process at this point is as
-follows:
-
-1. A maintainer will review your code and merge it if no changes are necessary.
-   Your change will be merged into the repository's `master` branch.
-1. If a maintainer has feedback or questions on your changes then they will set
-   `request changes` in the review and provide an explanation.
-
-## Using git
-
-For collaboration purposes, it is best if you create a GitHub account and fork
-the repository to your own account. Once you do this you will be able to push
-your changes to your GitHub repository for others to see and use, and it will
-be easier to send pull requests.
-
-If you are new to `git` and **GitHub** you are advised to start by the two
-following articles providing simple tutorials:
-- https://opensource.com/article/18/1/step-step-guide-git
-- https://opensource.com/article/19/7/create-pull-request-github
-
-GitHub official documentaiton is available at https://docs.github.com/en/github.
-
-### Branches and Commits
-
-You should submit your patch as a git branch named after the Github issue, such
-as `#3`\. This is called a _topic branch_ and allows users to associate a
-branch of code with the issue.
-
-It is the best practice to have your commit message have a _summary line_ that
-includes the issue number, followed by an empty line and then a brief
-description of the commit. This also helps other contributors understand the
-purpose of changes to the code.
-
-```text
-    #3 - platform_family and style
-
-    * use platform_family for platform checking
-    * update notifies syntax to "resource_type[resource_name]" instead of
-      resources() lookup
-    * GH-692 - delete config files dropped off by packages in conf.d
-    * dropped debian 4 support because all other platforms have the same
-      values, and it is older than "old stable" debian release
-```
-
-## Release cycle
-
-Master branch is always available.
-Tagged versions may be created as needed following [Semantic
-Versioning](https://semver.org/) as far as applicable.
-
-## Community
-
-EGI benefits from a strong community of developers and system administrators,
-and vice-versa. If you have any questions or if you would like to get involved
-in the wider EGI community you can check out:
-
-- [EGI Community Forum](https://community.egi.eu/)
-- [EGI website](https://www.egi.eu)
-
-**This file has been modified from the Chef Cookbook Contributing Guide**.
+Check the [contributing guide at GitHub](content/en/about/contributing/_index.md).

README.md

@@ -2,12 +2,15 @@
 
 [![Build Status](https://travis-ci.org/EGI-Foundation/documentation.svg?branch=master)](https://travis-ci.org/EGI-Foundation/documentation)
 
-Sources to build [EGI documentation static pages](https://egi-foundation.github.io/).
+Sources to build
+[EGI documentation static pages](https://egi-foundation.github.io/).
 
 - [Hugo](https://gohugo.io/) is used to build a static website.
 - The theme [docsy](https://www.docsy.dev) is used.
-- The static site is [deployed on GitHub](https://gohugo.io/hosting-and-deployment/hosting-on-github/) using a
-  dedicated [GitHub repository](https://github.com/EGI-Foundation/EGI-Foundation.github.io).
+- The static site is
+  [deployed on GitHub](https://gohugo.io/hosting-and-deployment/hosting-on-github/)
+  using a dedicated
+  [GitHub repository](https://github.com/EGI-Foundation/EGI-Foundation.github.io).
 
 ### Requirements
 
@@ -29,6 +32,7 @@ gem install mdl
 npm install postcss-cli@7.1.2
 npm install autoprefixer@9.0
 ```
+
 The supported Hugo version packages are available under the `binaries` folder.
 
 To build the site, from the repository root
@@ -66,8 +70,8 @@ git ci themes/docsy -m 'Update theme'
 
 ### Deploying to the EGI organisation pages
 
-To speed up the travis run a binary version of Hugo (extended version) for
-Linux 64 bit is included in the repository under `binaries`.
-Updates can be downloaded at https://github.com/gohugoio/hugo/releases.
+To speed up the travis run a binary version of Hugo (extended version) for Linux
+64 bit is included in the repository under `binaries`. Updates can be downloaded
+at https://github.com/gohugoio/hugo/releases.
 
 Travis will automatically deploy a new version when a PR is merged to master.

content/en/_index.md

@@ -18,7 +18,7 @@ description: "Documentation related to EGI activities"
     Learn More about EGI <i class="fas fa-arrow-alt-circle-right ml-2"></i>
   </a>
 
-  <a class="btn btn-lg btn-secondary mr-3 mb-4" href="https://github.com/EGI-Foundation/documentation/blob/master/CONTRIBUTING.md">
+  <a class="btn btn-lg btn-secondary mr-3 mb-4" href="{{< relref "/about/contributing" >}}">
     Contribute <i class="fab fa-github ml-2 "></i>
   </a>
   <p class="lead mt-5">EGI Documentation for users and service providers.</p>

content/en/about/_index.md

@@ -7,20 +7,18 @@ menu:
     weight: 40
 ---
 
-{{% alert %}}
-The documentation is maintained by the EGI Community, you can participate at
+{{% alert %}} The documentation is maintained by the EGI Community, you can
+participate at
 [EGI Documentation](https://github.com/EGI-Foundation/documentation).
 {{% /alert %}}
 
 ## Style guide
 
-{{% alert %}}
-The documentation should follow those guidelines:
-{{% /alert %}}
+{{% alert %}} The documentation should follow those guidelines: {{% /alert %}}
 
 - all files and folders should be lower case
 
 ## Acknowledgement
 
-- This documentation is built using the
-  [Docsy](https://github.com/google/docsy) Hugo theme.
+- This documentation is built using the [Docsy](https://github.com/google/docsy)
+  Hugo theme.

content/en/about/concepts/_index.md

@@ -5,6 +5,5 @@ type: docs
 weight: 20
 ---
 
-{{% pageinfo %}}
-This is a placeholder page that shows you how to use this template site.
-{{% /pageinfo %}}
+{{% pageinfo %}} This is a placeholder page that shows you how to use this
+template site. {{% /pageinfo %}}