You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/contrib/authoring-whats-new.md
+19-20Lines changed: 19 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,36 +2,41 @@
2
2
title: Writing What's new
3
3
---
4
4
5
-
The [What's new](https://energytransitionmodel.com/whats-new) page of the ETM describes the new features and bug fixes that have come with each monthly deploy. A guideline is presented here on how to write texts for the What's new, what features and bug fixes to include and the recommended structure for writing this. Note that the [guidelines for writing texts](./authoring-texts.md) should be followed as a basis when writing the What's new.
5
+
The [What's new](https://energytransitionmodel.com/whats-new) page of the ETM describes the new features and bug fixes that are released with each deploy. A guideline is presented here on how to write texts for the What's new, what features and bug fixes to include and the recommended structure for writing this. Note that the [guidelines for writing texts](./authoring-texts.md) should be followed as a basis when writing the What's new.
6
6
7
-
## General guidelines
7
+
## Guidelines
8
8
9
-
### What's new structure
9
+
### Structure
10
10
A section in the What's new is composed of the following categories:
11
-
***New features**: describes new or updated functionalities of the model, such as new technologies, sliders, charts and downloads.
12
-
***Bug fixes**: describes the bugs that have been fixed. This section is more technical than the New features and are less relevant for the general user. This section is collapsed by default.
11
+
***New features**: describes new or updated functionalities of the model, such as new technologies, sliders, charts and downloads.
12
+
***Bug fixes**: describes the bugs that have been fixed. This section is more technical than the New features and are less relevant for the general user. This section is collapsed by default.
13
13
***Technical changelog**: a CSV file containing information about changes made to inputs (sliders). This section is collapsed by default.
14
14
15
-
### Style and format
16
-
In addition to the [guidelines for writing texts](./authoring-texts.md), it is particularly important that the What's new text activates users to try out the new features themselves. This should be done by using an activating tone and referring to specific sections in the model (including hyperlink) where users can try out the new features. Furthermore, note that the content of the What's new is written in concise bullets.
17
-
18
15
### When to write a What's new
19
-
A new section of the What's new is generally written with each monthly deploy. If there is a deploy with no relevant changes to notify the users about, it can be decided to not write a What's new for that specific deploy.
16
+
A new section of the What's new is generally written with each deploy. If there is a deploy with no relevant changes to notify the users about, it can be decided to not write a What's new for that specific deploy.
20
17
21
18
### When to include a new feature or bug fix
22
-
New features and bug fixes should only be included in the What's new if it is relevant for users to know about these changes. It is important to consider this thoroughly to ensure that the What's new remains concise and reader-friendly. Generally, the following guidelines can be followed in this consideration:
19
+
New features and bug fixes should only be included in the What's new if it is relevant for users to know about these changes:
23
20
* Newly added sliders, technologies or user output should be included in the What's new.
24
-
* Changes to the model should be included if this could result in different scenario inputs or outcomes of existing scenarios, for example when existing modelling is changed (such as inputs or calculation modules) or when existing datasets are updated.
21
+
* Changes to the model should be included if this could result in different scenario inputs or outcomes of existing scenarios, for example when existing modelling is changed (such as inputs or calculation modules) or when existing datasets are updated.
25
22
* Changes that are more technical and where users are not going to experience any changes, should not be included in the What's new.
26
23
27
-
##Recommended structure
28
-
The recommended structure for writing about **New features**and **Bug fixes**, including good examples, is presented in this section.
24
+
### Style and format
25
+
In addition to the [guidelines for writing texts](./authoring-texts.md), it is particularly important that the What's new text activates users to try out the new features themselves. This should be done by using an activating tone and referring to specific sections in the model (including hyperlink) where users can try out the new features. Furthermore, note that the content of the What's new is written in concise bullets.
29
26
30
-
### New features
27
+
####New features
31
28
* The new or changed feature should be described in one sentence
32
29
* Bullets can be used if found necessary to provide more details about the new or changed feature, but make sure it remains concise
33
30
* Refer to sections in the ETM or to the documentation in the text using hyperlinks
34
31
32
+
#### Bug fixes
33
+
* Describe the involved bug
34
+
* Describe the implications of this bug in a way that users understand what went wrong or what modelling results were wrongly calculated
35
+
* Describe how it is fixed and, if relevant, if this fix affects other components
36
+
* If relevant, refer to sections in the ETM in the text using hyperlinks
37
+
38
+
## Example
39
+
35
40
:::info Example of a good new feature description
36
41
* New setup of the “My Scenarios” and “My Account” pages
37
42
* A [central environment](https://my.energytransitionmodel.com/) is introduced to manage saved scenarios, Collections, and account settings
@@ -41,12 +46,6 @@ The recommended structure for writing about **New features** and **Bug fixes**,
41
46
* Update personal information
42
47
:::
43
48
44
-
### Bug fixes
45
-
* Describe the involved bug
46
-
* Describe the implications of this bug in a way that users understand what went wrong or what modelling results were wrongly calculated
47
-
* Describe how it is fixed and, if relevant, if this fix affects other components
48
-
* If relevant, refer to sections in the ETM in the text using hyperlinks
49
-
50
49
:::info Example of a good bug fix description
51
50
* An issue in the [curtailment settings](https://energytransitionmodel.com/scenario/flexibility/flexibility_net_load/curtailment-solar-pv) for solar PV led to the wrong calculation of the peak production before curtailment. This issue is fixed, the correct peak production before curtailment is given. The production after curtailment remains unaffected.
0 commit comments