Publishing guidelines

This is as much a set of guidelines targeting everyone publishing content on the web as rules for reviewers to ensure no validation is forgotten before submitting for publication. It mostly targets our website but could generally apply to every content publicly exposed. It shall be considered as a moving content with new guidelines being added and others being altered.

Metadata

• One or multiple valid category are required, do not create too many, if none fit your topic, suggest a new one if previous published articles would be better associated with this new category.
• In most situation, only set one or two categories.
• Find the most appropriate tags, be careful not to create tags already present but with a different spelling, ensure an associated translation is created.
• If no tag fit your topic, suggest a new one, do not go too specific, try to find a few published articles which could be associated with this new category.
• A section at the end called “References” or “Bibliographie” is usually welcome.
• A feature image is required, ensure it doesn’t violate any copyright, ask for help if you don’t have the talent nor the inspiration.
• The feature image size must be 1800x900.
• Modify the permalink to be short and precise including the most relevant keywords for SEO. The permalink is the part of the URL which identify your article name. It is located below the title when editing an article.

Tone

• Keep a neutral tone, avoid using the first and second person.
• Avoid expressing judgements and opinions without a context and explicity introducing it as such.
• Humor can be used but with subtlety

Styles

• Balance paragraph size. Small paragraphs (eg one sentence, one line) are hard to visualize while longer ones are tiring to read.
• No line breaks in a paragraph (unless there is a reason for it)
• No empty lines are tolerated, such as between text or to position an image relative to a text, the same goes for multiple non-breaking spaces.
• Unless inappropriate, tables should have the following attributes: width: 100%, padding: 3px, border: 1, border-color: #ffffff, background-color: #f0f0f0.
• Consistent formatting of filenames, filepaths, name of tables, columns,… The recommended convention is:
  • Italic style for filenames, directory names, name of tables (data.csv, logs, table_cached etc.)
  • Quotes for filepaths, directory paths, columns in tables, tabs in webUI, values in text (“./logs/first.log”, “./logs”, “col”, “Storage”, “0 MB / 384.1 MB” etc.)

Markdown Specific Guidelines

• The markdown article should start with a header similar to the one below:

  ---
  title: Article full title
  date: 2019-05-20T20:00:00+00:00
  author: username
  permalink: readable-article-url-path
  feature: banner.jpg
  categories:
   - category
  tags:
   - tag1
   - tag2
  ---

• Use only the # to make headers. The following Headers guidelines also apply here.
• No line breaks in a paragraph. Markdown ignores them.
• Do not use the ------ element.
• Use ` ` for inline code snippets and ```<language> ``` for multi-line code snippets with a language indication for automatic syntax highlighting.
• Add an empty line after a paragraph, a header or an image.
• Avoid HTML tags, use only markdown.

Headers

• Start headers with heading 2, heading 1 is reserved for the title of the page.
• Avoid going too deep while using headers, usually, level 2 and 3 are enough.
• No style inside headers such as bold or italic, links are accepted.

Content

• Write a small introduction, without any heading, presenting the topic of the article (and not its context) with its most influent keywords
• Do not start with phrases like “in this article”
• Ensure the introduction displays as expected, next to the article title, on the blog page, the homepage or its category page.
• Names and technical concepts must be linked. Use Wikipedia if no official website exists.
• Links apply over the entire document and not only on the first occurrence of a word.
• Divide the article between clearly identified sections.
• Console output must be imported as text and not as a screenshot.
• In french, characters of two elements (eg ”:”) must be prefixed by a non-breaking space, not in english.

Spelling

• Text alignment should be justified
• Product and company name must be correctly capitalized, Node.js instead of nodejs, same for NVIDIA, Facebook, …
• A project name should be complete but it is tolerated to use their short version. Be consistent over the document. For example, the projects from The Apache Foundation should all be prefixed with “Apache” but it is ok to not do it; in such case, it is recommended to use Apache on the first occurrence of the name.
• List punctuation is not settled yet, we need to check what is the correct way to handle them but probably every element must start with an uppercase letter and finish with ”;” or ”.” for the last one.
• Review punctuation, ensuring they are no double spaces, spaces are correctly position (in French, double sign characters — ; : ? ! — require a space before, this isn’t the case in English), …
• Once ready, copy/paste your code inside a spell checker such as Grammarly or inside Libre Office or Microsoft Office, Reverso, BonPatron.

Code

• Commands, command arguments, variables, one line code, … should all be marked as inline code, the “inline” checkbox is on the top right corner of the code editor.
• Default code theme should be kept if possible to preserve forward compatibility in case of changes. We are still considering the following options: “Obsidian”, “Obsidian Light”, “Turnwall” and “Visual Assist”.

Translation

• Do not start the translation of your article before it is reviewed. Some contents require a lot of rewriting and it is discouraging having to translate twice an article.
• Copy/pasting from Google Translate requires cleaning the source code to remove occurrences of and proofreading.
• Re-apply all link URL after copy/pasting from Google Translate because they will point otherwise to a translated version.
• In case you are translating someone else’s article, it seems fair to leave the ownership to the original author, in which case it is necessary to update the “author” section below the text editor.

Publishing

• When the article is ready, mark its status as “pending review”, broadcast a message asking for reviewers and make sure the one or two people volunteering do their job until publication within a respected amount of time.
• Ask for review through the company messaging platform, using the #website channel.
• Broadcast the article to any appropriate social media including Reddit, Medium, HackerNews, LinkedIn, Twitter, …
• Articles are commonly published on Medium, Twitter and LinkedIn.

Gitlab Publishing

• Save all files related to the article in a sub-folder of src/md/blog in the website repository with the format yyyy-mm-dd-small-description
• Save your article markdown file with the format index..md
• Create an issue and merge request on the website Gitlab repository and use the appropriate tags throughout the article life cycle.
• The branch to merge should have the format /. You should check the other branches to match the category or event name.
• Delete your branch when the article has been published, close the issue and the merge request.
• Squash your commits when merging.
• If you open an issue or a merge request for an other author, be sure to include his/her name in the issue/merge request title.

Evaluation