Add considerations on hover alternative for mobile devices

A discourse has been added regarding the necessity of alternatives for hover interaction on mobile devices and possible approaches to solve such issues.
parent 1e8bf0f1
Pipeline #18440 passed with stages
in 4 minutes and 58 seconds
# Contribution Guide
Hey, you are interested in contributing to the web-page of _HIFIS Software_?
That is great, your help is much appreciated!
Please take some time to read about the Coding Guidelines and
Best Practices that were agreed upon.
If you have questions do not hesitate to contact a group member
of the development team.
Also, we are happy to learn what you think about this web-page
and get feedback regarding how to improve its appearance and content.
## Code Guidelines and Best Practices
### Common Style Guides
If you are about to contribute to this web-site we recommend to adhere to
common style guides for each language used.
Since we are using Jekyll to generate static web sites we mostly stick
to Markdown / Kramdown, HTML, CSS / SCSS and JavaScript.
Jekyll itself is written in Ruby.
Note:
In case you are just interested to know how to contribute with a
Blog Post to _HIFIS Software_ web-page you can find a
[Blog Post]({{ site.baseurl | append: '/hifis/blog/2019/10/09/Workflow-to-Create-a-new-Blog-Post.html' | relative_url }} "Workflow to Create a New Blog Post")
explaining the suggested workflow in the Blog Post section
of the web-page.
The following common style guides for each language used are just a
suggestion. We do not expect from you to rigorously comply to these
style guides. Nonetheless, they are a good starting point for
contributions according to Best Practices:
A first reference point is the
[Google Markdown Style Guide](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md "Google Markdown Style Guide").
The
[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html "Google HTML/CSS Style Guide").
is another good reference point if you are about to write HTML and CSS.
In order to generate CSS from SCSS there are the
[SASS Style Rules](https://sass-lang.com/documentation/style-rules "SASS Style Rules")
as well.
In terms of Javascript there is the
[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html "Google JavaScript Style Guide").
In the very unlikely case you are contributing to Jekyll or write your
own Jekyll plugins you should read also the
[Ruby Style Guide](https://rubystyle.guide/ "Ruby Style Guide").
This is a lot to read at the first glance, but it essentially saves you
and us time if you try to take these rules into account
right from the beginning, since these rule violations
might come up during the review process anyway.
### Style Checking Tools
Due to the fact that style guides are quite complex and to adhere to them
is a difficult task we recommend to consult dedicated tools to do the
checking for you.
Here comes the time saving into play.
| Static Code Analysis Tool | Language to Check |
|---|---|
| markdownlint | Markdown |
| HTML-Proofer | HTML|
| CSSLint | CSS |
| JSHint | JavaScript |
| Rubocop | Ruby |
#### markdownlint
[markdownlint](https://www.npmjs.com/package/markdownlint "markdownlint")
lets you check your Markdown. It is available as CLI-tool and
can be installed via npm and executed as follows:
```bash
$ npm install -g markdownlint
$ markdownlint path/to/markdown/folder/
```
#### HTML-Proofer
[HTML-Proofer](https://github.com/gjtorikian/html-proofer "HTML-Proofer")
lets you check your HTML. It is available as CLI-tool and
can be installed via gem and executed as follows:
```bash
$ gem install html-proofer
$ html-proofer path/to/html/folder/
```
#### CSSLint
[CSSLint](https://github.com/CSSLint/csslint/ "CSSLint")
lets you check your CSS. It is available as CLI-tool and
can be installed via npm and executed as follows:
```bash
$ npm install -g csslint
$ csslint path/to/css/folder/
```
#### JSHint
[JSHint](https://jshint.com/about/ "JSHint")
lets you check your JavaScript. It is available as CLI-tool and
can be installed via npm and executed as follows:
```bash
$ npm install -g jshint
$ jshint path/to/js/folder/
```
#### Rubocop
[Rubocop](https://github.com/rubocop-hq/rubocop "Rubocop")
lets you check your Ruby code. It is available as CLI-tool and
can be installed via gem and executed as follows:
```bash
$ gem install rubocop
$ rubocop path/to/ruby/code/folder/
```
## Contribution Workflow
### Workflow in a Nutshell
**1. Open an Issue, Share and Discuss the Topic**
Once you come up with an idea about how to contribute to _HIFIS Software_
web-page you can open a
[GitLab Issue](https://docs.gitlab.com/ce/user/project/issues/managing_issues.html#create-a-new-issue "Open a GitLab Issues")
and describe the bug you would like to fix, the feature you want to code
or the refactoring, testing or other quality assurance measures
you would like to implement.
Important:
Of course you need your own GitLab account of the
[HZDR GitLab](https://gitlab.hzdr.de/ "HZDR GitLab")
instance to do so as well as being added as a group member to the
development team.
Note:
At this point in time you would like to know more about the
branching model
[GitLab Flow](https://docs.gitlab.com/ce/topics/gitlab_flow.html "GitLab Flow")
that is supported by GitLab and the User-Interfaces of GitLab.
**2. Contribute with your Developments**
As soon as you would like to get to work you need to create your own
Git-branch.
Please give the branch a meaningful name according to the pattern
`<issue-number>-<branch-name>`.
It is good practice to check your code with static code checking tools
regularly as well as writing unit tests for your code.
Furthermore, when having unit tests in place as a safe guard you can
start refactoring your code to make it more readable, reusable,
testable, maintainable without changing the actual functionality
of your code.
Each Git-push to the remote Git repository will start a so called
_GitLab CI Pipeline_ to check that everything still works
as intended.
**3. The Review Process to Improve your Developments**
To enter the review process you need to open a
[GitLab Merge Request](https://docs.gitlab.com/ce/user/project/merge_requests/creating_merge_requests.html "GitLab Merge Request")
and assign it to your primary reviewer.
Give the merge request a meaningful title and description and
reference the original issue by stating `Closes #<issue-number>.`
in the description.
If applicable, give the title a name starting with `[WIP]`
to indicate that you are still working on it.
This allows previews and runs the GitLab CI/CD pipeline on your commits.
Also, set the `Progress::CanReview` label for the merge request,
so the others know you want to have it reviewed.
Discuss the changes suggested by your reviewers in dedicated discussion
threads in GitLab and agree upon how to integrate these suggestions into your
code to improve your developments.
Important:
Please do not rely on contributions that are not reviewed or
that are only reviewed by yourself.
This is an important quality gate.
After integration has been done and _GitLab CI Pipeline_
finishes successfully you are nearly crossing the finishing line.
**4. Integrate your Developments**
Once all discussion threads are resolved and the _GitLab CI Pipeline_
finishes successfully the primary reviewer can merge your branch into
branch _master_.
Be sure, we appreciate your contribution very much and thank you for
the great collaboration.
## Specific Aspects in our Style Guide
### User Interaction Considerations
**Offer Alternatives to Hover Interaction**
Keep in mind, that mobile devices like phones or tablets usually do not have the
ability to hover over an element on the website. Build alternatives for these
into your CSS and make sure they are used if the display is tablet-sized or
even smaller. Consult `_sass/_breakpoints.scss` for available breakpoints.
_More detailed discussion:_
Hovering is considered a good method to offer additional information without
forcing a context switch on the user (e.g. loading a new page or skipping to a
different part of the page).
Since for technical reasons this is not possible on mobile devices, an
alternative has to be considered for those. The usual approach is to entice the
user to click the element in question instead. To do so, it should be hinted to
the user that the element is clickable. If possible, use the websites default
link or button designs. In all other cases it can be achieved by either visual
styling (Since you can not use hover effects, consider subtle drop shadows) or
added badge icons
([Inspiration](https://www.flaticon.com/free-icons/hand-click)).
### CSS
**Avoid Magic Values**
Values that show up in _CSS_ may carry a semantic meaning, e.g. colors of the
color palette or device sizes.
Use the provided _SASS_ variables or named CSS values instead of hard-coding
magic values. Expand the set of variables, if required.
Example:
```scss
@import "colors"
p {
background-color: $color-helmholtz-blue;
color: white;
}
```
instead of
```scss
p {
background-color: #005AA0;
color: #fff;
}
```
See the `_sass` folder for definitions, grouped by context.
### HTML
**Write Comments in _Liquid_ tags**
Please use _Liquid_ comments in your HTML files to avoid them showing up in the
rendered version.
Example:
```liquid
<html>
{% comment %}
This text will not show up in the rendered HTML page.
It serves a documentary purpose only.
{% endcomment %}
</html>
```
instead of
```HTML
<html>
<!-- This is an HTML comment. It will be preserved and show up in the
rendered page, cluttering and bloating the delivered code. -->
</html>
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment