XS✔ ◾ Changes to rules to formatting new lines and inclusions in related rules

categories/communication/rules-to-better-email.md

@@ -95,6 +95,7 @@ index:
 - following-microsoft-365-groups
 - description-to-the-group
 - highlight-template-differences
+- format-new-lines
 
 ---
 

categories/design/rules-to-better-content-design.md

@@ -21,6 +21,7 @@ index:
 - distinguish-keywords-from-content
 - avoid-repetition
 - avoid-full-stops-in-bullet-point-lists
+- format-new-lines
 ---
 
 Content design helps create a frictionless user experience by presenting the right information in the right way and at the right time. This is an application of design thinking principles, improving the ways you structure and present user-oriented content. Effective content leads to better:

rules/format-new-lines/rule.md

@@ -1,92 +1,151 @@
 ---
 type: rule
-title: Do you know where to add new lines?
+title: Do you enhance readability with line breaks and spacing?
 uri: format-new-lines
 authors:
   - title: Brady Stroud
     url: https://ssw.com.au/people/brady-stroud
+  - title: Adam Cogan
+    url: https://www.ssw.com.au/people/adam-cogan/
+  - title: Josh Berman
+    url: https://www.ssw.com.au/people/josh-berman/
+  - title: Tiago Araujo
+    url: https://www.ssw.com.au/people/tiago-araujo
+  - title: Jayden Alchin
+    url: https://ssw.com.au/people/jayden-alchin/
 related:
   - add-useful-and-concise-figure-captions
   - use-the-right-html-figure-caption
 created: 2021-07-06T01:13:05.707Z
 archivedreason: ""
 guid: e05522a7-1822-412c-80ee-5619039f7d96
+
 ---
 
-Sometimes when writing content, you need to make the decision to keep it on the same line or put it on a new line.
+Writing in large blocks of text is a common practice, but it can hinder readability. Incorporating line breaks and spacing significantly enhances content readability. This allows readers to navigate through the text more easily, absorb information more effectively, and stay engaged with the material.
+
+<!--endintro-->
+
+::: info
+**Warning:** In web pages (HTML/Markdown), line breaks **should not be used to to create layout spacing** - it is a bad practice. You should use CSS margin and padding instead.
+Learn more on [HTML `<br>` Tag: The Dos and Don'ts of Adding an HTML Line Break](https://blog.hubspot.com/website/html-line-break).
+
+See the [Markdown Guide](https://www.markdownguide.org/basic-syntax/#line-breaks) for more information on line breaks in Markdown.
+
+On the other hand, in regards to **emails** and/or **informal documents**, line breaks can be used for spacing. In these cases, correct syntax is not crucial, and breaking a line is more convinient than dealing with margins/line spacing.
+:::
+
+### Long paragraphs
 
-It is recommended that notes, tips and figures should be on a new line to enable better readability. It can also be beneficial to bold those words.
+Consider breaking lines/paragraphs when you have a long block of text. You should aim to separate the information by context.
 
 ::: greybox
-Good way: use the Dynamics 365 (formerly CRM 2016) toolbar? 
-**Note:** We have a suggestion that Outlook should allow you to put the CRM2016 URL into Tools | Options so this is better integrated
+SSW is made up of a great team of staff that is passionate about technology and how it meets business needs. Today SSW has offices in Sydney, Melbourne, Brisbane, Newcastle, Strasbourg (France) and Hangzhou (China), with over 100 employees. Want to meet them? Have a look at SSW People.
 :::
 ::: bad  
-Figure: Bad Example - No line break before the note.
+Figure: Bad example - Long block of text
 :::
 
 ::: greybox
-Good way: use the Dynamics 365 (formerly CRM 2016) toolbar?  
-**Note:** We have a suggestion that Outlook should allow you to put the CRM2016 URL into Tools | Options so this is better integrated
+SSW is made up of a great team of staff that is passionate about technology and how it meets business needs.
+
+Today SSW has offices in Sydney, Melbourne, Brisbane, Newcastle, Strasbourg (France) and Hangzhou (China), with over 100 employees.
+
+Want to meet them? Have a look at SSW People.
 :::
 ::: good  
-Figure: Good Example - The note being on a fresh line makes it much easier to read.
+Figure: Good example - The text is separated by paragraphs
 :::
 
-This is also recommended when sending URLs for readability. 
+### Notes, Tips, PS
 
-::: greybox
-Hey Bob, 
-
-Check out this awesome new video about the SSW Cultural Exchange Program! https://youtu.be/dfE_Y8fy_wo?si=NEcQLAPafAWKa7m5
+Content elements like **Note**, **Tip**, **PS** (and similar) should be on a new line to enable better readability. It is beneficial to bold those words.
 
+::: greybox
+Test the login functionality thoroughly. Note: Try both valid and invalid credentials.
 :::
 ::: bad  
-Figure: Bad Example - No line break before the URL.
+Figure: Bad example - No line break before the note
 :::
 
 ::: greybox
-Hey Bob, 
+Test the login functionality thoroughly.
+**Note:** Try both valid and invalid credentials.
+:::
+::: good  
+Figure: Good example - The "Note" being on a fresh line and in bold makes it much easier to read
+:::
 
-Check out this awesome new video about the SSW Cultural Exchange Program! 
+### URLs
+
+Breaking a line is also recommended before URLs.
+
+::: greybox
+Check out these employment opportunities at SSW: <https://www.ssw.com.au/employment#available>
+:::
+::: bad  
+Figure: Bad example - No line break before the URL
+:::
 
-https://youtu.be/dfE_Y8fy_wo?si=NEcQLAPafAWKa7m5
+::: greybox
+Check out these employment opportunities at SSW:  
+<https://www.ssw.com.au/employment#available>
 :::
 ::: good  
-Figure: Good Example - The URL being on a fresh line makes it much easier to read.
+Figure: Good example - The URL being on a fresh line makes it much easier to read
 :::
 
-This is also recommended when sending PBIs for better readability.
+### Headings
+
+It's a good idea to have some space after headings.
 
 ::: greybox
-Hey Adam, 
+Hey Bob,
+Check out this awesome new video about the SSW Cultural Exchange Program!
+:::
+::: bad  
+Figure: Bad example - No spacing after heading
+:::
 
-I have 2 PBIs on my next to-do in the coming sprint: Product Backlog Item 88994: ⚡Performance | Create a new App Service plan and Product Backlog Item 88823: 🚗 Azure | Create a new App Service Plan in West US for SL production resource group.
-I will do the IoC after.
+::: greybox
+Hey Bob,
 
+Check out this awesome new video about the SSW Cultural Exchange Program!
+:::
+::: good  
+Figure: Good example - Spacing after heading
+:::
+
+### Multiple items should be a list
+
+If you text has information that can become multiple items, it should be a list. For example, when sending PBIs for a Sprint.
+
+::: greybox
+I have 2 PBIs in the coming Sprint: Product Backlog Item 88994: Performance | Create a new App Service plan and Product Backlog Item 88823: Azure | Create a new App Service Plan in West US for SL production resource group. I will do the IoC after.
 :::
 ::: bad  
-Figure: Bad Example - No new lines for PBIs.
+Figure: Bad example - Block of text
 :::
 
 ::: greybox
-Hey Adam,
+I have 2 PBIs in the coming Sprint:
+
+* PBI 88994: Performance | Create a new App Service plan
+* PBI 88823: Azure | Create a new App Service Plan in West US for SL production resource group
 
-I have 2 PBIs in this Sprint:
-- PBI 88994: ⚡Performance | Create a new App Service plan 
-- PBI 88823: 🚗 Azure | Create a new App Service Plan in West US for SL production resource group.
 I will do the IoC after.
 
 :::
 ::: good  
-Figure: Good Example - PBIs on a new line.
+Figure: Good example - List is used to separate information and make it easier to digest
 :::
 
-<!-- TODO: Add CodeAuditor box -->
-::: info 
-This rule is enforced by CodeAuditor. https://codeauditor.com/rules
-:::
+**Note:** On the example above, see how changing from "Product Backlog Item" to "PBI" also helps with readability. However you should [only use acronyms when you know the recipient is familiar with the term](/avoid-acronyms).
 
-See the [Markdown Guide](https://www.markdownguide.org/basic-syntax/#line-breaks) for more information on line breaks.
+### Images and captions
 
+It is also recommended to include spaces after an image or a figure description. These elements need breathing space to help users focus on them.
 
+::: info
+In web, always rely on CSS margins to achieve this.
+:::