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/contributing/index.md
+107-7Lines changed: 107 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -55,14 +55,59 @@ If you don't get a timely reply, ask the documentation owners for a review or fo
55
55
56
56
## Guidelines
57
57
58
-
### Frequently Asked Questions
58
+
### Links
59
59
60
-
The documentation does not have a FAQ section, because questions are best answered by the documentation, not in a separate section.
61
-
Integrating information into the main documentation requires some care to identify where the information needs to go, and edit the documentation around it.
62
-
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.
60
+
#### External Links
63
61
64
-
FAQ content, such as lists of most frequently encountered error messages, is still very useful in many contexts.
65
-
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].
The CI/CD pipeline will fail if it detects broken links in your draft documentation.
78
+
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.
79
+
80
+
Adding and maintaining links to internal pages and sections that don't break or conflict requires care.
81
+
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.
82
+
83
+
Instead, we advocate adding unique references to sections.
84
+
85
+
=== "adding a reference"
86
+
87
+
Add a reference above the item, in this case we want to link to the section with the title `## The Fast Server`:
88
+
89
+
```
90
+
[](){#ref-servers-fast}
91
+
## Fast Server
92
+
```
93
+
94
+
Use the `[](){#}` syntax to define the reference/anchor.
95
+
96
+
!!! note
97
+
Always place the anchor above the item you are linking to.
98
+
99
+
=== "linking to a reference"
100
+
101
+
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):
102
+
103
+
```
104
+
[the fast server][ref-servers-fast]
105
+
```
106
+
107
+
The benefits of this approach are that the link won't break if
108
+
109
+
* either the file containing the link or the file that refers to the link move,
110
+
* or if the title of the target sections changes.
66
111
67
112
### Images
68
113
@@ -79,7 +124,62 @@ Images are stored in the `docs/images` directory.
79
124
!!! tip
80
125
Do you need a screenshot, or can a text description also work?
81
126
82
-
## Small Contributions
127
+
### Text Formatting
128
+
129
+
Turn off automatic line breaks in your text editor, and stick to one sentence per line in paragraphs of text.
130
+
131
+
See the good and bad examples below for an example of of what happens when a change to a sentence forces a line rebalance:
132
+
133
+
=== "good"
134
+
Before:
135
+
```
136
+
There are many different versions of MPI that can be used for communication.
137
+
The final choice of which to use is up to you.
138
+
```
139
+
140
+
After:
141
+
```
142
+
There are many different versions of the popular MPI communication library that can be used for communication.
143
+
The final choice of which to use is up to you.
144
+
```
145
+
146
+
The diff in this case affects only one line.
147
+
148
+
=== "bad"
149
+
Before:
150
+
```
151
+
There are many different versions of MPI that
152
+
can be used for communication. The final choice
153
+
of which to use is up to you.
154
+
```
155
+
156
+
After:
157
+
```
158
+
There are many different versions of the popular
159
+
MPI communication library that can be used for
160
+
communication. The final choice of which to use
161
+
is up to you.
162
+
```
163
+
164
+
The diff in this case affects the original 3 lines, and creates a new one.
165
+
166
+
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.
167
+
168
+
* changes to the text are less likely to create merge conflicts
169
+
* changing one line of text will not modify the surrounding lines (see example above)
170
+
* git diffs and git history are easier to read.
171
+
172
+
### Frequently Asked Questions
173
+
174
+
The documentation does not have a FAQ section, because questions are best answered by the documentation, not in a separate section.
175
+
Integrating information into the main documentation requires some care to identify where the information needs to go, and edit the documentation around it.
176
+
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.
177
+
178
+
FAQ content, such as lists of most frequently encountered error messages, is still very useful in many contexts.
179
+
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].
180
+
181
+
182
+
### Small Contributions
83
183
84
184
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.
0 commit comments