From ec026014f2ea995bbd2b921b722e92f584a9ccc7 Mon Sep 17 00:00:00 2001 From: bcumming Date: Fri, 21 Mar 2025 15:39:54 +0100 Subject: [PATCH 1/9] add linking and line breaking best practices to the contributing guide --- docs/contributing/index.md | 114 ++++++++++++++++++++++++++++++++++--- 1 file changed, 107 insertions(+), 7 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 677a81b9..8a5aae79 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -55,14 +55,59 @@ If you don't get a timely reply, ask the documentation owners for a review or fo ## Guidelines -### Frequently Asked Questions +### Links -The documentation does not have a FAQ section, because questions are best answered by the documentation, not in a separate section. -Integrating information into the main documentation requires some care to identify where the information needs to go, and edit the documentation around it. -Adding the information to a FAQ is easier, but the result is information about a topic distributed betwen the docs and FAQ questions, which ultimately makes the documentation harder to search. +#### external links -FAQ content, such as lists of most frequently encountered error messages, is still very useful in many contexts. -If you want to add such content, create a section at the bottom of a topic page, for example this section on the [SSH documentation page][ref-ssh-faq]. +Links to external sites use the `[]()` syntax: + +=== "external link syntax" + + ``` + [The Spack repository](https://github.com/spack/spack) + ``` + +=== "result" + + [The Spack repository](https://github.com/spack/spack) + +#### internal links + +!!! note + The CI/CD pipeline will fail if it detects broken links in your draft documentation. + it is not completely foolproof - to ensure that your changes do not create broken links you should merge the most recent version of the `main` branch of the docs into your branch branch. + +Adding and maintaining links to internal pages and sections that don't break or conflict requires care. +it is possible to refer to links in other files using relative links, for example `[the fast server](../servers.md#fast-server)`, however if the target file is moved, or the section title "fast-server" is changed, the link will break. + +Instead, we advocate adding unique references to sections. + +=== "adding a reference" + + Add a reference above the item, in this case we want to link to the section with the title `## the fast server`: + + ``` + [](){#ref-servers-fast} + ## fast server + ``` + + Use the `[](){#}` syntax to define the reference/anchor. + + !!! note + Always place the anchor above the item you are linking to. + +=== "linking to a reference" + + In any other file in the project, use the `[][]` syntax to refer to the link (note that this link type uses square braces, instead of the usual parenthesis): + + ``` + [the fast server][ref-servers-fast] + ``` + +The benefits of this approach are that the link won't break if + +* either the file containing the link or the file that refers to the link move; +* or if the title of the target sections changes. ### Images @@ -79,7 +124,62 @@ Images are stored in the `docs/images` directory. !!! tip Do you need a screenshot, or can a text description also work? -## Small Contributions +### Text formatting + +Turn off automatic line breaks in your text editor, and stick to one sentence per line in paragraphs of text. + +See the good and bad examples below for an example of of what happends when a change to a sentence forces a line rebalance: + +=== "good" + Before: + ``` + There are many different versions of MPI that can be used for communication. + The final choice of which to use is up to you. + ``` + + After: + ``` + There are many different versions of the popular MPI communication library that can be used for communication. + The final choice of which to use is up to you. + ``` + + The diff in this case affects only one line. + +=== "bad" + Before: + ``` + There are many different versions of MPI that + can be used for communication. The final choice + of which to use is up to you. + ``` + + After: + ``` + There are many different versions of the popular + MPI communication library that can be used for + communication. The final choice of which to use + is up to you. + ``` + + The diff in this case affects the original 3 lines, and creates a new one. + +This method defines a canonical represention of text, i.e. there is one and only one way to write a paragraph of text, which plays much better with git. + +* changes to the text are less likely to create merge conflicts +* changing one line of text will not modify the surrounding lines (see example above) +* git diffs and git history are easier to read. + +### Frequently Asked Questions + +The documentation does not have a FAQ section, because questions are best answered by the documentation, not in a separate section. +Integrating information into the main documentation requires some care to identify where the information needs to go, and edit the documentation around it. +Adding the information to a FAQ is easier, but the result is information about a topic distributed betwen the docs and FAQ questions, which ultimately makes the documentation harder to search. + +FAQ content, such as lists of most frequently encountered error messages, is still very useful in many contexts. +If you want to add such content, create a section at the bottom of a topic page, for example this section on the [SSH documentation page][ref-ssh-faq]. + + +### Small Contributions Small changes that only modify the contents of a single file, for example to fix some typos or add some clarifying detail to an example, it is possible to quickly create a pull request directly in the browser. From 6da438fe188a1bda51cfb0fbee75e8f18d1b896f Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Fri, 21 Mar 2025 16:17:13 +0100 Subject: [PATCH 2/9] Update docs/contributing/index.md Co-authored-by: Mikael Simberg --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 8a5aae79..f9cdc99b 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -57,7 +57,7 @@ If you don't get a timely reply, ask the documentation owners for a review or fo ### Links -#### external links +#### External Links Links to external sites use the `[]()` syntax: From 97a628cc350fbd988e4d2b78778b008c1368b59c Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Fri, 21 Mar 2025 16:17:18 +0100 Subject: [PATCH 3/9] Update docs/contributing/index.md Co-authored-by: Mikael Simberg --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index f9cdc99b..a9431b67 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -71,7 +71,7 @@ Links to external sites use the `[]()` syntax: [The Spack repository](https://github.com/spack/spack) -#### internal links +#### Internal Links !!! note The CI/CD pipeline will fail if it detects broken links in your draft documentation. From 284f4001a7e090093ddaebe03956aeaac94716a8 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Fri, 21 Mar 2025 16:18:00 +0100 Subject: [PATCH 4/9] Update docs/contributing/index.md Co-authored-by: Mikael Simberg --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index a9431b67..4fd7868a 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -75,7 +75,7 @@ Links to external sites use the `[]()` syntax: !!! note The CI/CD pipeline will fail if it detects broken links in your draft documentation. - it is not completely foolproof - to ensure that your changes do not create broken links you should merge the most recent version of the `main` branch of the docs into your branch branch. + It is not completely foolproof - to ensure that your changes do not create broken links you should merge the most recent version of the `main` branch of the docs into your branch branch. Adding and maintaining links to internal pages and sections that don't break or conflict requires care. it is possible to refer to links in other files using relative links, for example `[the fast server](../servers.md#fast-server)`, however if the target file is moved, or the section title "fast-server" is changed, the link will break. From 0300ff2c8ef811a600c4c3082e1249d7f9df87d1 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Fri, 21 Mar 2025 16:18:35 +0100 Subject: [PATCH 5/9] Update docs/contributing/index.md Co-authored-by: Mikael Simberg --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 4fd7868a..e956e6e6 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -78,7 +78,7 @@ Links to external sites use the `[]()` syntax: It is not completely foolproof - to ensure that your changes do not create broken links you should merge the most recent version of the `main` branch of the docs into your branch branch. Adding and maintaining links to internal pages and sections that don't break or conflict requires care. -it is possible to refer to links in other files using relative links, for example `[the fast server](../servers.md#fast-server)`, however if the target file is moved, or the section title "fast-server" is changed, the link will break. +It is possible to refer to links in other files using relative links, for example `[the fast server](../servers.md#fast-server)`, however if the target file is moved, or the section title "fast-server" is changed, the link will break. Instead, we advocate adding unique references to sections. From a08c17f854bb835d00b5ecec898420b5fecbbb19 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Fri, 21 Mar 2025 16:18:52 +0100 Subject: [PATCH 6/9] Update docs/contributing/index.md Co-authored-by: Mikael Simberg --- docs/contributing/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index e956e6e6..a99dbd60 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -84,11 +84,11 @@ Instead, we advocate adding unique references to sections. === "adding a reference" - Add a reference above the item, in this case we want to link to the section with the title `## the fast server`: + Add a reference above the item, in this case we want to link to the section with the title `## The Fast Server`: ``` [](){#ref-servers-fast} - ## fast server + ## Fast Server ``` Use the `[](){#}` syntax to define the reference/anchor. From 02ced7d583f11cf88d6d0bbdc9e30361a6cfea26 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Fri, 21 Mar 2025 16:19:13 +0100 Subject: [PATCH 7/9] Update docs/contributing/index.md Co-authored-by: Mikael Simberg --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index a99dbd60..e7604613 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -128,7 +128,7 @@ Images are stored in the `docs/images` directory. Turn off automatic line breaks in your text editor, and stick to one sentence per line in paragraphs of text. -See the good and bad examples below for an example of of what happends when a change to a sentence forces a line rebalance: +See the good and bad examples below for an example of of what happens when a change to a sentence forces a line rebalance: === "good" Before: From 7a07ad60bf6bc62e927a0c2db8e160836ea73d29 Mon Sep 17 00:00:00 2001 From: Ben Cumming Date: Fri, 21 Mar 2025 16:19:48 +0100 Subject: [PATCH 8/9] Update docs/contributing/index.md Co-authored-by: Mikael Simberg --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index e7604613..1783511b 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -106,7 +106,7 @@ Instead, we advocate adding unique references to sections. The benefits of this approach are that the link won't break if -* either the file containing the link or the file that refers to the link move; +* either the file containing the link or the file that refers to the link move, * or if the title of the target sections changes. ### Images From f2f56433997c7767c3b0fbefdc59499e1125f69b Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Fri, 21 Mar 2025 16:27:02 +0100 Subject: [PATCH 9/9] Update docs/contributing/index.md --- docs/contributing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 1783511b..680bc052 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -124,7 +124,7 @@ Images are stored in the `docs/images` directory. !!! tip Do you need a screenshot, or can a text description also work? -### Text formatting +### Text Formatting Turn off automatic line breaks in your text editor, and stick to one sentence per line in paragraphs of text.