From dac0e1b1619e8a1d3077263ede22b3cb44ec7b1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tiago=20Ara=C3=BAjo=20=5BSSW=5D?= Date: Wed, 27 Mar 2024 17:36:13 -0700 Subject: [PATCH] =?UTF-8?q?XS=E2=9C=94=20=E2=97=BE=20More=20improvements?= =?UTF-8?q?=20to=20the=20new=20lines=20rule=20(#8273)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * More improvements to the new lines rule * Auto-fix Markdown files --------- Co-authored-by: github-actions[bot] --- rules/format-new-lines/rule.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/rules/format-new-lines/rule.md b/rules/format-new-lines/rule.md index 16d954a1823..5831ab294a7 100644 --- a/rules/format-new-lines/rule.md +++ b/rules/format-new-lines/rule.md @@ -6,13 +6,13 @@ authors: - title: Brady Stroud url: https://ssw.com.au/people/brady-stroud - title: Adam Cogan - url: https://www.ssw.com.au/people/adam-cogan/ + url: https://www.ssw.com.au/people/adam-cogan - title: Josh Berman - url: https://www.ssw.com.au/people/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/ + url: https://ssw.com.au/people/jayden-alchin related: - add-useful-and-concise-figure-captions - use-the-right-html-figure-caption @@ -27,10 +27,12 @@ Writing in large blocks of text is a common practice, but it can hinder readabil ::: 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. +**Warning:** For web (HTML/Markdown), line breaks **should not be used to to create layout spacing**! +You should use CSS margin and/or padding instead. + Learn more on [HTML `
` 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. +See the [more information on line breaks in Markdown](https://www.markdownguide.org/basic-syntax/#line-breaks). 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. ::: @@ -116,9 +118,9 @@ Check out this awesome new video about the SSW Cultural Exchange Program! Figure: Good example - Spacing after heading ::: -### Multiple items should be a list +### Multiple items as lists -If you text has information that can become multiple items, it should be a list. For example, when sending PBIs for a Sprint. +If you text has information that can be turned into multiple items, you should do so, by creating 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. @@ -140,12 +142,9 @@ I will do the IoC after. Figure: Good example - List is used to separate information and make it easier to digest ::: -**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). +**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 the recipient is familiar with the term](/avoid-acronyms). ### 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. -:::