Add page regarding content guidelines (#339)

Co-authored-by: Benjamin Uekermann <[email protected]>
Co-authored-by: Gerasimos Chourdakis <[email protected]>

_data/sidebars/docs_sidebar.yml

@@ -591,8 +591,8 @@ entries:
       url: /docs-meta-overview.html
       output: web
 
-    - title: Migration guide
-      url: /docs-meta-migration-guide.html
+    - title: Content guidelines
+      url: /docs-meta-content-guidelines.html
       output: web
 
     - title: Cheatsheet
@@ -615,3 +615,8 @@ entries:
       url: /docs-meta-search.html
       output: web
 
+    - title: Migration guide
+      url: /docs-meta-migration-guide.html
+      output: web
+
+

pages/docs/docs-meta/docs-meta-content-guidelines.md

@@ -0,0 +1,53 @@
+---
+title: Content guidelines
+permalink: docs-meta-content-guidelines.html
+keywords: pages, migration, guideline, content, best practices, style guide
+summary: "Learn which style to follow when writing documentation and how to write good titles, content, and page summaries."
+---
+
+## Language & style
+
+This is the style we aim for, even if not all documentation pages are currently ticking all the boxes (nice opportunity for [contributing](community-contribute-to-precice.html)):
+
+- Target group: scientists & engineers with some but limited experience with programming and with Linux, but extended experience with simulations.
+- Informal style and active voice: imagine you are explaining each concept to a colleague over coffee.
+- Concise, yet complete: short pages are completely fine and even preferred, as long as all the important information is there.
+- Incomplete/imperfect documentation is better than no documentation: try to contribute anything you can, and we can always improve it.
+- We use `Sentence case for headings`, not `Title Case for Headings`. The reason is that we find that it is visually clearer, easier to keep it consistent, and we do not need to mix content with style.
+- Descriptive links: avoid forms such as `you can find the documentation [here](target)`, prefer forms such as `see the [documentation](target)`.
+- We use American English.
+
+## Titles
+
+- Always specify a `title:`
+- Keep it short, specific, and avoid boilerplate.
+- Avoid duplicate titles.
+- Don't include navigational context such as `preCICE.org |`, `preCICE Documentaion -`. Jekyll does this automatically.
+
+More information on the [title link guide from Google](https://developers.google.com/search/docs/appearance/title-link#page-titles).
+
+## Page summary
+
+- Always specify a `summary:`
+- This text may be chosen as the preview text under a search result.
+- Write a flowing text. Multiple sentences are fine.
+- Summarize the whole page and be specific.
+- Include important information like dates.
+
+See full [snippet and meta-description guide from Google](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions)
+
+## Images
+
+- Always specify a textual description using the full Markdown syntax: `![DESCRIPTION](LINK TO IMAGE)`. This is important both for crawlers and for screen readers.
+- For rasterized graphics use PNG or [`WebP`](https://repology.org/project/libwebp/versions). For the latter, convert images using [`img2webp`](https://developers.google.com/speed/webp/docs/img2webp) with `img2webp image.png -o image.webp`.
+- For animations use [`WebP`](https://repology.org/project/libwebp/versions). Convert exisiting GIFs using [`gif2webp`](https://developers.google.com/speed/webp/docs/gif2webp) or create new animations with `ffmpeg -i image%d.png -loop 0 output.webp`.
+- For vectorized graphics use SVG. Make sure text renders correctly outside your browser by using common fonts or converting text to paths. In case of the latter, also add the original SVG to simplify future modifications.
+- Choose a descriptive filename
+
+See full [image best practices from Google](https://developers.google.com/search/docs/appearance/google-images).
+
+## General content
+
+- Avoid boilerplate content and get to the point as quickly as possible.
+- If content already exists on another side, prefer linking to it. Simplifying, customizing, or summarizing external content is fine. Don't copy chunks of documentation.
+- Follow the guide on [creating helpful, reliable, people-first content by Google](https://developers.google.com/search/docs/fundamentals/creating-helpful-content)

pages/docs/docs-meta/docs-meta-overview.md

@@ -5,6 +5,10 @@ summary: "This page is an introduction to the development of the preCICE documen
 permalink: docs-meta-overview.html
 ---
 
+## About the content
+
+This majority of this documentation focuses on the technical side of writing content. See [our content guidelines](docs-meta-content-guidelines.html) to learn what the content should look like.
+
 ## About the theme
 
 This site is based on a jekyll theme by technical writer Tom Joht called [documentation-theme-jekyll](https://github.com/tomjoht/documentation-theme-jekyll). At the time of writing this theme was the second most popular documentation-style jekyll theme on [jamstackthemes.dev](https://jamstackthemes.dev/#ssg=jekyll) and has been selected for its rich feature set and clean, functional design out of the box.
@@ -123,17 +127,6 @@ The `permalink` has to be the full file name ending in `.html` with no leading s
 
 The [Migration Guide](docs-meta-migration-guide.html) contains more information on how to migrate preCICE documentation pages from the preCICE Github Wiki.
 
-## Language & style
-
-As we recently (December 2020) migrated our documentation from multiple sources to this website, you may find different styles and inconsistencies among different pages. However, here is what we aim for:
-
-- Target group: scientists & engineers with some but limited experience with programming and with Linux, but extended experience with simulations.
-- Informal style and active voice: imagine you are explaining each concept to a colleague over coffee.
-- Concise, yet complete: short pages are completely fine and even preferred, as long as all the important information is there.
-- Incomplete/imperfect documentation is better than no documentation: try to contribute anything you can and we can always improve it.
-- We use `Sentence case for headings`, not `Title Case for Headings`. The reason is that we find that it is visually clearer, easier to keep it consistent, and we do not need to mix content with style.
-- Descriptive links: avoid forms such as `you can find the documentation [here](target)`, prefer forms such as `see the [documentation](target)`.
-
 ## Rendering content from external repositories
 
 While the main content of this website is sourced from the same [repository](https://github.com/precice/precice.github.io) that hosts the mechanics of it, some content is sourced from separate repositories. The main reason is to keep the documentation next to the respective code, so that developers can view it without looking at the website and update it in the same contribution, while users can find everything in the same place. Read more about this concept in the [preCICE v2 reference paper](https://doi.org/10.12688/openreseurope.14445.2). This practice is not yet uniformly adopted, but we are working on migrating more content.