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
+19-6Lines changed: 19 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,15 @@
4
4
This documentation is developed using the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) framework, and the source code for the docs is publicly available on [GitHub](https://github.com/eth-cscs/cscs-docs).
5
5
This means that everybody, CSCS staff and the CSCS user community can contribute to the documentation.
6
6
7
+
## Making suggestions or small changes
8
+
9
+
If you have a suggestion, comment or small change to make when reading the documentation, there are three ways to reach out.
10
+
11
+
1.**Edit the page inline**: click on the :material-pencil: icon on the top right hand corner of each page, and make the change inline. When you click "commit", and create a pull request, which will then be reviewed by the CSCS docs team.
12
+
1.**Create a GitHub issue**: create an issue on the [issue page](https://github.com/eth-cscs/cscs-docs/issues) on the GitHub repository.
13
+
1.**Create a CSCS service desk ticket**: create a ticket on the CSCS service desk.
14
+
This is useful if you don't have a GitHub account, or would prefer not to use Github.
15
+
7
16
## Before starting
8
17
9
18
The CSCS documentation takes contributions from all CSCS staff, with a _core team_ of maintainers responsible for ensuring that the overall documentation is well organised, that pages are well written and up to date, and that contributions are reviewed and merged as quickly as possible.
@@ -19,7 +28,7 @@ The CSCS documentation takes contributions from all CSCS staff, with a _core tea
19
28
20
29
!!! tip "Before contributing"
21
30
Please read the [guidelines][] and [style guide][] before making any contribution.
22
-
Consistency and common practices make it easier for users to read and navigate the documentation, and these guides are directed towards this.
31
+
Consistency and common practices make it easier for users to read and navigate the documentation, make it easier for regular contributors to write, and avoid style debates.
23
32
We try to strike a balance between following the guidelines and letting authors write in a style that is comfortable for them.
24
33
25
34
To speed up the merge process and avoid lengthy style discussions, we reserve the right to make changes to pull requests to bring it into line with the guidelines.
@@ -88,18 +97,22 @@ Then navigate to GitHub, and create a pull request.
88
97
89
98
## Review process
90
99
91
-
Documentation is maintained by everybody - so don't be afraid to jump in and make changes or fixes where you see the need or the potential.
100
+
After you have made a pull request, a CI/CD pipeline will run the [spell checker][ref-contributing-spelling] and build a copy of the docs with the PR changes.
101
+
A temporary "TDS" copy of the docs is deployed, to allow reviewers to see the finished documentation, at the address `https://docs.tds.cscs.ch/$PR`, where `PR` is the number of the pull request.
92
102
93
-
If you plan to make significant changes, please discuss them with an [issue](https://github.com/eth-cscs/cscs-docs/issues) beforehand, to ensure the changes will fit into the larger documentation structure.
103
+
To make changes based on reviewer feedback, make a new commit on your branch, and push it to your fork.
104
+
The PR will automatically be updated, the spell checker will run again, and the TDS documentation site will be rebuilt.
94
105
95
-
If you think your documentation update could affect specific stakeholders, ping them for a review.
96
-
The same applies if you are not getting get a timely reply for your pull request.
97
-
You can get some hints of whom to contact by looking at [CODEOWNERS](https://github.com/eth-cscs/cscs-docs/blob/main/.github/CODEOWNERS).
106
+
!!! tip
107
+
If you think your documentation update could affect specific stakeholders, ping them for a review.
108
+
You can get some hints of whom to contact by looking at [CODEOWNERS](https://github.com/eth-cscs/cscs-docs/blob/main/.github/CODEOWNERS).
109
+
If they don't reply in a timely manner, reach out to the core docs team to expedite the process.
98
110
99
111
!!! note
100
112
To minimise the overhead of the contributing to the documentation and speed up "time-to-published-docs" we do not have a formal review process.
101
113
We will start simple, and add more formality as needed.
102
114
115
+
[](){#ref-contributing-spelling}
103
116
### Spell checker
104
117
105
118
A spell checker workflow runs on all PRs to help catch simple typos.
0 commit comments