Skip to content

Commit 06e1fc4

Browse files
committed
add "small contributions" section, and cover TDS builds in review process
1 parent 4bda4c3 commit 06e1fc4

File tree

1 file changed

+19
-6
lines changed

1 file changed

+19
-6
lines changed

docs/contributing/index.md

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,15 @@
44
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).
55
This means that everybody, CSCS staff and the CSCS user community can contribute to the documentation.
66

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+
716
## Before starting
817

918
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
1928

2029
!!! tip "Before contributing"
2130
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.
2332
We try to strike a balance between following the guidelines and letting authors write in a style that is comfortable for them.
2433

2534
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.
8897

8998
## Review process
9099

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.
92102

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.
94105

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.
98110

99111
!!! note
100112
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.
101113
We will start simple, and add more formality as needed.
102114

115+
[](){#ref-contributing-spelling}
103116
### Spell checker
104117

105118
A spell checker workflow runs on all PRs to help catch simple typos.

0 commit comments

Comments
 (0)