FAQ/Guidelines

[Q&A] General
1

Translation missing: en.guidelines_topic.body

2

Edit the first post in this topic to change the contents of the FAQ/Guidelines page.

3

Guidelines

Keep articles as short as possible by cutting functionally independent parts into different articles

Example:

  1. Activity content blocks require knowledge of activities and export definitions
  2. Traditional activity templates require knowledge about export definitions
  3. Export definitions do not need knowledge about activities or templates and have their right on it’s own

So we can write it into 3 posts

  1. Export definitions / how to use export engine
  2. Activity templates, with a reference to export definitions. Than on top of the article, we can say ‘we assume that you know the export engine, please see this post for more info’ (or something like that)
  3. Activity templates with content blocks, referring to the two above

This helps as:

  1. We get an export definition post
  2. A simple one for activities
  3. A complex one for activities

The search / related post of Discourse is so good that we see the other products automatically at the bottom.

Make a summary at the top

We are not writing a ‘who did it’ crime novel, but learning material :slight_smile:
So therefore, the first part of the post must describe what:

  1. it is about
  2. When relevant: other related posts that are assumed prior knowlege
  3. Which components, datasets, plug-ins or framework versions are required

For component names, just refer them by the number. The names or unfortunately (May 2024) mostly in Dutch but will be re-named. I have asked Joachim to create a Discourse plugin to retrieve real-time the names of the components with a mouseover.

Plug-ins are in English and should be named with their name.

Screenshots

For screenshots, to make it nice and readible:

  1. Always in the most recent Framework version (so 3.8/3.9, not 3.7 - except of course for the App Server until that one is on 3.8, expected June 2024)
  2. When possible: create screenshots in a demo / test environment so we do not need to blur. Blurring is ugly / makes peole distracted, etc. Of course, when there is no other option, please blur all sensitive data
  3. Cut out the URL of the application: cropping rather than blurring

For highlighting:

  1. Crop is preferred over highlighting. When cropping is done nicely, highlight is often not needed. See Expressions in Novulo - Wiki - Novulo
  2. When highlighting, we choose the Light Green #65CC00 from Greenshot, line size=2, Shadow = OFF

Sequence and set-up

First explain generally and conceptually
Then, after the general explanation is done, add screenshots as an example

Language

We can do 99% in English. There is no need to have Dutch translations in the title or captions of the posts. For example, this not needed. When people search through google, Google will translate for you anyway

image
image970×218 16 KB

Sometimes, in the text, you can use a Dutch word if it really helps Dutch readers. But it must be the exception.