Add guide for writing slider texts to for contributors

[mabijkerk]

Slider texts are currently heterogenous in structure. We want a single homogeneous structure that can then be applied to all slider texts. We want to capture this structure in a short guide that contributors can use when writing slider texts.

• [x] Draft guide @kaskranenburgQ
• [ ] Review guide by other Quintellers
• [ ] Finish guide @kaskranenburgQ

Inspiration for the guide can be drawn from https://github.com/quintel/etmodel/issues/4023. Key is to start with short and simple guide, that can easily be maintained and is not too much of an effort to read.

[kaskranenburgQ]

This is the first draft for the guide:

Goal slider information: inform and direct to extra information. A good slider text has the following aspects:


• Informs the user about the sliders functionality
• Shortly explains which exact type of technique was modelled
• Which other sliders effect the properties of this technology
• Where the user might find more detailed information Language: British English / Dutch (ABN) with a preference for British English.   User Type: Adult energy 'experts' or those aspiring to attain expertise in the subject matter. Focus on users already familiar with the topic. Avoid long explanations of the technique or trends, rather focus on what is meant by this technique (short definition) and how this technique is modelled (if relevant).   Tone: Formal yet constructive and activating. Use active and concise sentences. Prioritize readability, avoiding unnecessary technical jargon, and aim to nudge users toward understanding and utilizing the ETM effectively.   Style: Visual emphasis, utilize elements like arrows for brevity. Consistency in style to enable users to quickly scan and locate specific information.   Recommended slider text Structure:  
  1. Purpose (Max 20 Words):    Clearly state the slider's purpose in a brief sentence.      Example: This slider adjusts the total installed capacity of autothermal reformers (ATR).  
  2. Background (50-100 Words):    Provide concise background information about the associated technology or technique. Include a definition, usage, and, if relevant, advantages, disadvantages, or links to documentation.      Example: ATR is a method for syngas/biofuel production, combining partial oxidation and steam methane reforming. It allows flexible hydrogen-to-carbon monoxide ratios for varied biofuel production. For more information, checkout the documentation [Documentation Link].  
  3. Special Notes:    Include any necessary warnings or additional information users should be aware of regarding the slider's effects or workings.      Example: Note: ATR emits CO directly into the air, this means…  
  4. Connections to Other Sliders (1 Sentence or Bullet List):    Clearly explain any connections to other sliders within the model, providing links or references.   Example: Go to Emissions > CCUS > Capture of CO2 to install CO capture or the production of pure hydrogen production. Go to Costs & Efficiencies > Hydrogen > Hydrogen production for changing costs and efficiency.  
  5. Next Steps:    Reminds users of the existence of the technical and financial properties.      Example: Explore technical and financial properties for detailed information.

[mabijkerk]

Nice work @kaskranenburgQ! Some notes:

• I see some overlap in the first paragraph "A good slider text has the following aspects:" and then the "Recommended slider text Structure:". Can't we leave out the first?
• I'm not really sure what to do with this information: "Visual emphasis, utilize elements like arrows for brevity. Consistency in style to enable users to quickly scan and locate specific information."
• I would rephrase "purpose" to something like "What does the slider do?"
• I would rephrase "special notes" to something like "How to set the slider at an appropriate value?" and move it from element 3 to 2
• I would rephrase "Other sliders" to "other elements": we can also refer to charts, data-exports etc. etc. You may also add an example for how to refer to sliders and charts
• 5 seems a bit excessive to repeat in every slider, I would remove this
• Following the discussion with Anthony in https://github.com/quintel/etmodel/issues/4023#issuecomment-1291969421 I would structure links to other slides as follows:
  • Hydrogen production section
  • de sectie Waterstofproductie

I would recommend you write a draft guide on a branch, open a pull request and then mark it for review by @Charlottevm and me.