Rewrite slider texts using homogeneous structure

[Charlottevm]

Slider information is quite diverse when it comes to the type and amount of information that is given and the way it is presented. Sometimes a lot of information is given, sometimes only one sentence. Sometimes the language is informal, sometimes very formal. Etc.

For example, see this slider information for LED-lighting vs. slider information for household batteries

Of course this is logical seeing that the sliders have been added over a long period in time and by many different people. However, we could try to create a more standardized way of presenting information in general and in particular for slider information in the future.

Disadvantages:

• Less freedom to communicate that which is relevant for a particular slider (even though a good format can/should still provide the amount of necessary freedom)

Advantages:

• Easier to read for users (they know which information they can expect)
• Easier to write for us (we know what information should be in there)
• We make a conscious choice what we do want to include (e.g. links, info about the technology) and do not want to include (e.g. information that expires, information you can find on wikipedia), in what tone (formal, informal, activating, scientific,..) and in which structure (first this, then that)
• More professional

Since it is probably quite the excercise to reform and update all slider information, I would propose we reach consensus around the slider information for any slider we add, change or test from here on.

How do you feel about this @marliekeverweij @mabijkerk @ChaelKruip @antw?

If you agree I can post a structure I have in mind which I've used during previous projects, would love to hear which structure/form you use and see if we can agree on something standardized!

[mabijkerk]

I wholeheartedly agree with this idea. I'm all for standardising the components, style and structure of slider texts.

[antw]

If you agree I can post a structure I have in mind which I've used during previous projects, would love to hear which structure/form you use and see if we can agree on something standardized!

Please do!

There was an article recently by Wix who overhauled their error messages to be clearer and use a standard structure. Perhaps this might be of some inspiration?

[mabijkerk]

Additionally, I woud be useful to have clear rules on cross-referencing, in both English and Dutch. Do we always spell out the full link, do we use arrows, do we refer to slides or sections, what part of the reference do we highlight:

• Go to Supply -> Hydrogen -> Hydrogen production
• See the Hydrogen production section
• See the hydrogen production slide
• ...

In Dutch specifically, I often see different ways of adding the word 'sectie':

• Waterstofproductiesectie
• Waterstofproductie-sectie
• Waterstofproductie sectie

[Charlottevm]

See my proposal below, please feel free to change/add anything, this is just something to start the conversation :). Probably this will be a work in progress anyways because it might not fit every possible slider yet.
I've added/changed a thing here and there based on the website you mentioned @antw.
And good points about the style of the text @mabijkerk, I completely agree.

Language: British English / Dutch (ABN)
Personally I think Brirish English is nicer and it reflects our partly british team ;-).

User type: Adult energy 'experts' (in the making)
ETM-users are mostly adults with a certain level of expertise (or wanting to get to a certain level of expertise). Written information should be focused on those users that want to learn more about how it is modelled within the ETM and what we mean exactly with a certain topic or slider. It should not be focused on users that are not aware of the existence of a topic or technique. In that last case I think a short wikipedia visit would remedy this as explaining everything fully in the ETM is unnecessary and mostly clogs userbrains with an overload of information. It should at most spike the interest in a certain technique or briefly describe its advantages and disadvantages/why it is part of the ETM.

Tone: formal but constructive and activating
In my opinion this matches the user type described above. This means (I would say) we use 'you' in English and 'u' in Dutch and deflect from asking (obvious) questions as if the tool were to be used only by (inexperienced) students. However, I would always opt for texts that are easy to read (e.g. short sentences!), constructive/helpful (no overload of technical jargon, focus on helping user) and activating (nudge the user into understanding and using the ETM to its full capacity by directing the user to other connected sliders/slides).

Question: should we avoid using 'you' or 'u' alltogether? On the one hand it makes it more personal but I feel it sometimes comes across as a bit 'informal' or too directive, rather I would want to sound more generic. Furthermore, talking directly at a user makes it more 'activating' and you need less words e.g. "You can checkout the..." vs "Checkout the ..."

Goal slider information: inform and direct to extra information/sliders
As mentioned above, a good slider text:
- informs the user what the slider does exactly
- 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

Style: As visual as can be
To reduce the amount of text necessary to convey our message I would opt for using things like arrows to starkly reduce sentences like 'look at the ... slider within the .... section' and instead use "Go to slide > slider for more information". By consistently using these style items users can (at some point) quickly scan through a slider text and find the specific information they are looking for because they know what it looks like.

Structure:

1. Describe what the slider does (max. 20 words)
2. Describe technology/slider background information (between 50-100 words)

• Definition of technique, what it is used for
• If necessary: Advantage / disadvantage of technique (e.g. if the technique is more novel)
• If present: For more information a link to documentation or papers

3. If necessary: Warn users about the effects or workings of this slider if this is different than that which is described above (e.g. if the slider has certain side-effects that are not directly visible or logical)
4. If present: Connection to other slides/sliders within the model (Use one sentence to explain and/or bullet list if there are multiple links, e.g. to cost, efficiency or ccs sliders regarding the same technology)
5. If present: Direct users to click on 'technical and financial properties' for information on costs etc.

Example:

Use this slider to adjust the total installed capacity of autothermal reformers (ATR).

Autothermal reforming (ATR) is a production method for syngas/biofuels: a combination of hydrogen (H2) and carbon monoxide (CO). It combines partial oxidation (POX) and steam methane reforming (SMR) within one reactor. The advantage of this production method is that the ratio between hydrogen and carbon monoxide (H2:CO) can be varied. This is useful for the production of (different types of) biofuels. The disadvantage is a lower energy efficiency in comparison to an SMR. For more information on hydrogen production, see the documentation.

Note: in this case the ATR produces pure hydrogen and CO is emitted directly into the air.

To change properties of the ATR, go to:
• Emissions > CCUS > Capture of CO2 (to capture the CO and produce pure hydrogen)
• Costs & Efficiencies > Hydrogen > Hydrogen production (to change future costs and efficiency of this technology)

For more technology specifications, checkout the technical and financial properties below.

Would love to hear what you think and which additions/changes you would like to make!

[mabijkerk]

It should not be focused on users that are not aware of the existence of a topic or technique

I think this is a very important discussion point, because it depends on what insight we want to generate. For some users for example, ammonia might be a very novel topic. Should we just assume they will first read up on the topic before going back to the ETM?

Structure

What I'm not seeing here is some guidance on how the user should set the slider. What key points should the user consider when selecting a value.

Aside from these two main points that I wanted to mention, I think Github might not be the best location for this discussion. I would propose that @Charlottevm and I flesh out her proposal a bit more and then plan a meeting to discuss the key points. We could aim to create a README in the locales folder of ETModel that contains writer's guidelines for slider texts.

[antw]

@Charlottevm: Personally I think Brirish English is nicer and it reflects our partly british team ;-).

Haha, don't feel compelled to use British English on my account. I tend to use American English in code just because it's a common convention. I'd say opt for whatever you think will be most familiar to our main audience. Since that tends to be EU countries, I think we should use whatever version of English is most commonly taught/used in the EU. I expect that's British, but follow the data.

@mabijkerk: Do we always spell out the full link, do we use arrows, do we refer to slides or sections, what part of the reference do we highlight:

• Go to Supply -> Hydrogen -> Hydrogen production
• See the Hydrogen production section
• See the hydrogen production slide
  ...

I prefer the second one. I used to opt for the first quite frequently, because I think the structure of the ETM can be confusing to newcomers, but it's also quite long and noisy and at risk of becoming out of date if we change that structure. I'm not a fan of the third simply because "slide" is a technical term with little meaning to visitors.

@Charlottevm Question: should we avoid using 'you' or 'u' alltogether? On the one hand it makes it more personal but I feel it sometimes comes across as a bit 'informal' or too directive, rather I would want to sound more generic. Furthermore, talking directly at a user makes it more 'activating' and you need less words e.g. "You can checkout the..." vs "Checkout the ..."

I like the second example – "Check out the ..." – more. Not because it's more formal (I don't see a problem with being slightly informal) but because it gets straight to the call to action without unnecessary words.

[github-actions]

This issue has had no activity for 60 days and will be closed in 7 days. Removing the "Stale" label or posting a comment will prevent it from being closed automatically. You can also add the "Pinned" label to ensure it isn't marked as stale in the future.

[mabijkerk]

@Charlottevm I would propose that @kaskranenburgQ picks up this issue and writes a first short guide, which we can then review. Two questions:

1. Does this work for you?
2. Where should this guide be posted: wiki on ETModel or on our documentation? I would prefer the first.

[Charlottevm]

1. Yes this certainly helps @mabijkerk , thanks for picking this up @kaskranenburgQ !

2. This effort got stranded in the discussion on where the guide should be posted. @noracato's opinion was in the documentation and my opinion was in the wiki on ETModel (for which you need to have the rights attributed to your github account, only Nora and Thomas have those at the moment). Maybe a quick round of votes in the modelling and development team could solve this issue @mabijkerk ? (as I think I am the only one in the advisory team who has an opinion on this matter, but correct me if I am wrong)

[Charlottevm]

What is your image on the goal of:

• Documentation
• Read-me (for every repository)
• Wiki (for every repository)

@redekok @noracato @thomas-qah @mabijkerk @kaskranenburgQ ?

[Charlottevm]

Goal per medium:

• Documentation - Tells you how to use the ETM
• Read-me (for every repository) - Tells you what the goal of the repository is and what is consists of
• Wiki (for every repository) - Tells you how to develop the ETM

For me this caters the 3 different groups of users of the ETM:

1. General users who would like to have more information on how to use the ETM or the additional tooling that is available
2. Users who want to clone the ETM and understand how the back-end works
3. Users who are also developers

[noracato]

Goal per medium:

• Documentation – Tells you how to use the ETM, has a seperate section for contributors (this means also ourselves) where deeper explanations and standards can live, a section about the scenario-tools, and a section with our API reference. The documentation documents the full open source project so not only its use and workings, but also how you can incorporate it in your own project, and how you can install and develop your own version.
• Read-me (for every repository) –Tells you what the goal of the repository is and what is consists of, short install instructions
• Wiki (for every repository) - Unnecesary

I am highly opposed to the idea of a wiki. We made a decision to collect all documentation in one place, and almost all our current information is already part of that space. It is unwise to create a new place where some of the information lives for arbitrary reasons. Right now everything is organised and easily searchable, let's not change that!

[mabijkerk]

I would say that he benefit of having a central place for all of our documentation is significant: the default for the type of information addressed in this issue should therefore be the "For contributors" pages of our documentation. There are two reasons to diverge from this:

1. The information in question is sensitive/internal: in this case we can use dropbox or the internal repository
2. The information is question is specific: in this case I think we should choose whether to use a README or Wiki pages

Let's discuss this proposal in the teammeeting.

[mabijkerk]

I have opened a new issue for writing the "slider texts guide" in quintel/documentation#166.
I have renamed this issue to refer to the process of actually rewriting the sliders using the homogeneous structure presented in the guide.