Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
about:guidelines [2026/04/15 21:33] – vso_vsoabout:guidelines [2026/04/29 14:18] (current) – vso_vso
Line 2: Line 2:
  
 <WRAP meta> <WRAP meta>
-version: 8.3+version: 8.4
 updated: 8 April 2026 updated: 8 April 2026
 status: published status: published
Line 8: Line 8:
  
 <WRAP intro> <WRAP intro>
-This guide covers the principles, process, and standards that apply to every topic page. Please read this carefuly before making any contributions to the wiki. For markup syntax and formatting examples, see the [[about:markup|Wiki markup]] reference.+This guide covers the principles, process, and standards that apply to every topic page. Please read this carefully before making any contributions to the wiki.
 </WRAP> </WRAP>
  
  
-===== Wiki principles =====+===== Main ideas ===== 
 + 
 +==== Wiki principles ====
  
 These principles apply to how the wiki is developed and maintained. These principles apply to how the wiki is developed and maintained.
Line 32: Line 34:
 | **Copyright** | For any image, confirm the license permits its use and include attribution and a source link. | | **Copyright** | For any image, confirm the license permits its use and include attribution and a source link. |
  
-===== The three perspectives =====+==== The three perspectives ====
  
 Smart grid transitions cannot be fully understood from any one disciplinary perspective. For instance, while engineering as a field allows to focus on what is technically feasible, institutional analysis highlights how rules and incentives make certain options viable. Further, exploring the perspectives of various actors underlines their distinct visions, needs and practices. Each approach illuminates something the others might miss, and each does not provide a complete outlook on any given topic. One can therefore use triangulation of different perspectives to gain a better outlook on the realities of energy transitions. Smart grid transitions cannot be fully understood from any one disciplinary perspective. For instance, while engineering as a field allows to focus on what is technically feasible, institutional analysis highlights how rules and incentives make certain options viable. Further, exploring the perspectives of various actors underlines their distinct visions, needs and practices. Each approach illuminates something the others might miss, and each does not provide a complete outlook on any given topic. One can therefore use triangulation of different perspectives to gain a better outlook on the realities of energy transitions.
Line 41: Line 43:
 A finding that holds across different perspectives is more credible than one that depends on a single method or theory. A finding that holds across different perspectives is more credible than one that depends on a single method or theory.
 </WRAP> </WRAP>
-{{:oscardamen_perspective_overlay_traingulation.png?600|Triangulation diagram}}+{{:0:oscardamen_perspective_overlay_traingulation.png?600|Triangulation diagram}}
  
 Every topic is explored from three perspectives. These are not separate sections to fill in independently; they are lenses that together give a fuller picture of how a smart grid concept operates in the real world. Where the perspectives interact, or where one uniquely exposes something the others miss, this should be made explicit in the text. The three perspectives also have some resemblance to how the wiki is structured, but this structuring works somewhat differently. While a topic might belong in the "Technologies & Infrastructure" category because of how it is commonly used, it still benefits from having three different perspectives filled out as other disciplines might have other interpretations. Every topic is explored from three perspectives. These are not separate sections to fill in independently; they are lenses that together give a fuller picture of how a smart grid concept operates in the real world. Where the perspectives interact, or where one uniquely exposes something the others miss, this should be made explicit in the text. The three perspectives also have some resemblance to how the wiki is structured, but this structuring works somewhat differently. While a topic might belong in the "Technologies & Infrastructure" category because of how it is commonly used, it still benefits from having three different perspectives filled out as other disciplines might have other interpretations.
Line 72: Line 74:
 </WRAP> </WRAP>
  
-===== Language, tone and voice ===== 
  
-Topics should read as though written by a knowledgeable colleague explaining +===== Process =====
-something clearly. It should be direct and precise, with focus on building +
-shared understanding.+
  
-**Language rules:** +==== Roles ====
-  * Use UK English spelling throughout: //organise//, //recognise//, //analyse//', +
-    //colour//, //behaviour//, //centre//. If in doubt, consult an authoritative +
-    UK dictionary such as Oxford or Collins. +
-  * Use plain language. If a technical term is necessary, define it on first use. +
-  * Prefer active constructions: "Several countries have introduced regulatory +
-    sandboxes" rather than "Regulatory sandboxes have been established." +
-  * Prefer //can// and //could// over //should// when describing possibilities. +
-    The wiki describes what is done and what options exist. It does not prescribe +
-    what countries ought to do. +
-  * Avoid hollow evaluative phrases: "a fundamental shift", "a critical enabler", +
-    "plays an increasingly important role." State what changed and why it matters. +
-  * Avoid generic prose markers: "It is important to note that", +
-    "This section explores", "Moreover", "Furthermore." +
-  * Avoid unnecessary introductions: "In an era of increasing complexity", +
-    "Given the rapidly evolving landscape." +
-  * Vary sentence length for readability and flow; avoid overly long sentences. +
- +
-**Headings:** All section headings use sentence case. Write "Why this matters", +
-not "Why This Matters". +
- +
-===== Roles =====+
  
 Wiki development is a co-creative process. Every topic has a small team. Wiki development is a co-creative process. Every topic has a small team.
Line 116: Line 94:
 | **Inter-working group meeting** | Endorses the shared definition. Endorsement is required before a topic is published and again if the shared definition is subsequently changed. | | **Inter-working group meeting** | Endorses the shared definition. Endorsement is required before a topic is published and again if the shared definition is subsequently changed. |
  
-===== Becoming a lead author =====+==== Becoming a lead author ====
  
 Lead authors are the core of the wiki and every topic needs one. Lead authors take responsibility for a topic from first draft to publication: organising input from co-authors, coordinating the review process, addressing comments, and keeping the topic current after it is published. Lead authors are the core of the wiki and every topic needs one. Lead authors take responsibility for a topic from first draft to publication: organising input from co-authors, coordinating the review process, addressing comments, and keeping the topic current after it is published.
Line 132: Line 110:
 **To propose a new topic:** See the [[about:newtopic|New topic]] guide. **To propose a new topic:** See the [[about:newtopic|New topic]] guide.
  
-===== Editorial process =====+==== Editorial process ====
  
 The process has three stages and three decision gates. Gate 1 is a lead author self-check before external review begins. Gate 2 is the substantive quality threshold before endorsement. The process has three stages and three decision gates. Gate 1 is a lead author self-check before external review begins. Gate 2 is the substantive quality threshold before endorsement.
Line 188: Line 166:
 Milestone 3: Topic is ready for publication. Milestone 3: Topic is ready for publication.
  
-===== Sensitivity rating =====+==== Topic status ====
  
-Topics may be assigned sensitivity ratings, however how they should function is still to be decided. At the moment no sensitivity ratings are assigned.+Each topic carries a status visible on the start page and on the topic page. The lead author is responsible for keeping it current. Only topics with status ''published'', ''under-approval'', ''in-review'', or ''draft'' are counted as active topics.
  
-===== Versioning =====+<WRAP tablecap> 
 +**Table 6.** Topic status values, transitions, and gate anchors. 
 +</WRAP> 
 + 
 +^ Status ^ Meaning ^ Enters when ^ Exits when ^ 
 +| **Published** | Live and publicly visible. | Stage 4 upload is complete. | A major revision begins, returning the topic to ''draft''. | 
 +| **Under approval** | Quality review is complete; the topic is awaiting endorsement at an inter-WG meeting. | Gate 2 is passed. | The shared definition is endorsed at an inter-WG meeting. | 
 +| **In review** | Under editorial revision and quality panel review. Expert input is especially valuable at this stage. | Gate 1 is passed. | Gate 2 is passed. | 
 +| **Draft** | Actively being written or undergoing major revision. | Work begins, or a major version bump is made. | Gate 1 is passed. | 
 +| **Planned** | Content exists from an earlier wiki version but has not been updated to the current template and standards. | Old content is confirmed to exist. | Restructuring begins, moving the topic to ''draft''. | 
 +| **Backlog** | Topic identified; nothing written yet. | The topic is added to the registry. | Work begins, moving the topic to ''draft''. | 
 + 
 +==== Versioning ====
  
 Every topic page carries a version number. The version and status move together at defined triggers. Every topic page carries a version number. The version and status move together at defined triggers.
Line 212: Line 202:
 Start at version 1.0 on first publication. Update the version number and the updated date in the page metadata on every change. Use the optional topic notes section to record what changed between versions. Start at version 1.0 on first publication. Update the version number and the updated date in the page metadata on every change. Use the optional topic notes section to record what changed between versions.
  
-===== Topic page structure =====+==== Sensitivity rating ====
  
-Every topic page follows the same structure. Sections must appear in this order.+Topics may be assigned sensitivity ratings, however how they should function is still to be decided. At the moment no sensitivity ratings are assigned.
  
-<WRAP tablecap> +==== Comment system ====
-**Table 5.** Required sections for every topic page, in order. +
-</WRAP> +
- +
-^ # ^ Section ^ Purpose ^ +
-| 1 | Category badge | Identifies which of the five categories this topic belongs to. | +
-| 2 | Title | The topic name. | +
-| 3 | Metadata block | Records lead authors, contributors, reviewers, version, date, sensitivity, status, and AI use. Drives the status display and author attribution on the start page. | +
-| 4 | Intro panel | One paragraph defining the topic and situating it in smart grid transitions. Every sentence must be specific to this topic. | +
-| 4b | Insight block | A single plain-text sentence, 120–160 characters, no links or markup. Not visible on the topic page; feeds the topic card on the start page. | +
-| 5 | Why this matters | One to two paragraphs and one callout box explaining why the topic matters for smart grid transitions. | +
-| 6 | Shared definitions | The working definition, with an optional table for multi-dimensional concepts. | +
-| 7 | Perspectives | Three subsections (Actors and stakeholders, Technologies and infrastructure, Institutional structures), each with one paragraph and one to three case examples. | +
-| 8 | Distinctions and overlaps | Two to five entries clarifying what this topic is not, and where it borders adjacent concepts. | +
-| 9 | Related topics | Direct links to other topic pages using ''%%[[topics:slug|Title]]%%'' format. Not tags. | +
-| 10 | References | Full APA 7th edition, auto-generated from inline footnotes. | +
-| 11 | Topic notes | Editorial working notes, gap log, AI attribution, and verification record. Not published on the live wiki. | +
- +
-For markup syntax and code examples for each section, see the [[about:markup|Wiki markup]] reference. +
- +
-===== Topic status ===== +
- +
-Each topic carries a status visible on the start page and on the topic page. The lead author is responsible for keeping it current. Only topics with status ''published'', ''under-approval'', ''in-review'', or ''draft'' are counted as active topics. +
- +
-<WRAP tablecap> +
-**Table 6.** Topic status values, transitions, and gate anchors. +
-</WRAP> +
- +
-^ Status ^ Meaning ^ Enters when ^ Exits when ^ +
-| **Published** | Live and publicly visible. | Stage 4 upload is complete. | A major revision begins, returning the topic to ''draft''. | +
-| **Under approval** | Quality review is complete; the topic is awaiting endorsement at an inter-WG meeting. | Gate 2 is passed. | The shared definition is endorsed at an inter-WG meeting. | +
-| **In review** | Under editorial revision and quality panel review. Expert input is especially valuable at this stage. | Gate 1 is passed. | Gate 2 is passed. | +
-| **Draft** | Actively being written or undergoing major revision. | Work begins, or a major version bump is made. | Gate 1 is passed. | +
-| **Planned** | Content exists from an earlier wiki version but has not been updated to the current template and standards. | Old content is confirmed to exist. | Restructuring begins, moving the topic to ''draft''. | +
-| **Backlog** | Topic identified; nothing written yet. | The topic is added to the registry. | Work begins, moving the topic to ''draft''. | +
- +
-===== Comment system =====+
  
 Every topic page allows for comments from lead authors, contributors and reviewers within the main body of the text. Every topic page allows for comments from lead authors, contributors and reviewers within the main body of the text.
Line 271: Line 225:
   * Mark a passage for follow-up after a meeting   * Mark a passage for follow-up after a meeting
  
-===== AI use =====+ 
 +===== Writing guidelines ===== 
 + 
 +==== Language, tone and voice ==== 
 + 
 +Topics should read as though written by a knowledgeable colleague explaining 
 +something clearly. It should be direct and precise, with focus on building 
 +shared understanding. 
 + 
 +**Language rules:** 
 +  * Use UK English spelling throughout. 
 +  * Use plain language. If a technical term is necessary, define it on first use. 
 +  * Prefer active constructions: "Several countries have introduced regulatory sandboxes" rather than "Regulatory sandboxes have been established." 
 +  * Prefer can and could over should when describing possibilities. The wiki describes what is done and what options exist. It does not prescribe what countries ought to do. 
 +  * Avoid hollow evaluative phrases: "a fundamental shift", "a critical enabler", "plays an increasingly important role." State what changed and why it matters. 
 +  * Avoid generic prose markers: "It is important to note that", "This section explores", "Moreover", "Furthermore." 
 +  * Avoid unnecessary introductions: "In an era of increasing complexity", "Given the rapidly evolving landscape." 
 +  * Vary sentence length for readability and flow; avoid overly long sentences. 
 +  * All section headings use sentence case. Write "Why this matters", not "Why This Matters". 
 + 
 +==== Topic page structure ==== 
 + 
 +Every topic page follows the same structure. Sections must appear in this order. 
 + 
 +<WRAP tablecap> 
 +**Table 5.** Required sections for every topic page, in order. 
 +</WRAP> 
 + 
 +^ # ^ Section ^ Purpose ^ Word count ^ 
 +| 1 | Category badge | Identifies which of the five categories this topic belongs to. | — | 
 +| 2 | Title | The topic name. | — | 
 +| 3 | Metadata block | Records lead authors, contributors, reviewers, version, date, sensitivity, status, and AI use. Drives the status display and author attribution on the start page. | — | 
 +| 4 | Intro panel | One paragraph defining the topic and situating it in smart grid transitions. Every sentence must be specific to this topic. | 80–120 words | 
 +| 4b | Insight block | A single plain-text sentence, 120–160 characters, no links or markup. Not visible on the topic page; feeds the topic card on the start page. For backlog and planned topics, leave the block structurally present but empty. | 120–160 characters | 
 +| 5 | Why this matters | One to two paragraphs and one callout box explaining why the topic matters for smart grid transitions. | 150–250 words | 
 +| 6 | Shared definitions | The working definition, with an optional table for multi-dimensional concepts. | 80–150 words | 
 +| 7 | Perspectives | Three subsections (Actors and stakeholders, Technologies and infrastructure, Institutional structures), each with one paragraph and one to three case examples. | 120–200 words per subsection | 
 +| 8 | Distinctions and overlaps | Two to five entries clarifying what this topic is not, and where it borders adjacent concepts. | 30–60 words per entry | 
 +| 9 | Related topics | Direct links to other topic pages using ''%%[[topics:slug|Title]]%%'' format. 3–7 links, substantive connections only. Not tags. | — | 
 +| 10 | References | Auto-generated from inline DokuWiki footnotes placed throughout body text. No section heading required. | — | 
 +| 11 | Topic notes | Editorial working notes, gap log, AI attribution, and verification record. Not published on the live wiki. | — | 
 + 
 +For markup syntax and code examples for each section, see the [[about:markup|Wiki markup]] reference. 
 + 
 +==== AI use ====
  
 AI tools may be used in wiki development when helpful, but their use is not required or expected. Where AI is used, it can help reorganise source material into the template structure, improve sentence flow, reformat references, or convert approved documents into DokuWiki markup. AI tools may be used in wiki development when helpful, but their use is not required or expected. Where AI is used, it can help reorganise source material into the template structure, improve sentence flow, reformat references, or convert approved documents into DokuWiki markup.
Line 302: Line 300:
 .vh-entry .vh-body p:last-child { margin-bottom: 0; } .vh-entry .vh-body p:last-child { margin-bottom: 0; }
 </style> </style>
 +<details class="vh-entry">
 +<summary>Version 8.3 — 20 April 2026 <span class="vh-tag">Restructured into four parts; topic structure table updated</span></summary>
 +<div class="vh-body">
 +<p>Guide restructured into four parts: Main ideas, Process, Writing guidelines, and Version history. Wiki principles and The three perspectives moved to lead the document. Language, tone and voice, Topic page structure, and AI use consolidated into Writing guidelines. Topic page structure table updated: word counts added for all substantive sections, References description corrected to reflect inline footnote behaviour, Insight block note added for backlog and planned topics, Related topics link-count constraint (3–7) added. Markup reference link relocated from intro to end of Topic page structure section.</p>
 +</div>
 +</details>
 <details class="vh-entry"> <details class="vh-entry">
 <summary>Version 8.2 — 8 April 2026 <span class="vh-tag">Approval distinctions and version record added</span></summary> <summary>Version 8.2 — 8 April 2026 <span class="vh-tag">Approval distinctions and version record added</span></summary>
Line 311: Line 315:
 <summary>Version 7 — 17 March 2026 <span class="vh-tag">Expanded tone and voice and clarified terminology</span></summary> <summary>Version 7 — 17 March 2026 <span class="vh-tag">Expanded tone and voice and clarified terminology</span></summary>
 <div class="vh-body"> <div class="vh-body">
-<p>Critical reflexivity returned as a listed principle, and the idea of knowledge integration was broadened to include tacit knowledge shared across teams. Sections on tone and voice were expanded, giving more detail on writing style. The procedure for addressing reviewer comments at Gate 2 was clarified. Updated terminology from “page owner” to “lead author”</p>+<p>Critical reflexivity returned as a listed principle, and the idea of knowledge integration was broadened to include tacit knowledge shared across teams. Sections on tone and voice were expanded, giving more detail on writing style. The procedure for addressing reviewer comments at Gate 2 was clarified. Updated terminology from "page owner" to "lead author"</p>
 </div> </div>
 </details> </details>
Line 341: Line 345:
 <summary>Version 2 — July 2024 <span class="vh-tag">Refined text and updated title</span></summary> <summary>Version 2 — July 2024 <span class="vh-tag">Refined text and updated title</span></summary>
 <div class="vh-body"> <div class="vh-body">
-<p>The text was lightly refined throughout, and the document’s title was updated to “ISGAN Smart Grids Transitions Wiki — Editorial Guide.”</p>+<p>The text was lightly refined throughout, and the document's title was updated to "ISGAN Smart Grids Transitions Wiki — Editorial Guide."</p>
 </div> </div>
 </details> </details>