docs-reorg: introduce "Join the community" section #746
Conversation
fenekku
commented
Mar 7, 2025
•
fenekku
commented
- This reorganizes the "Onboard & Contribute" section to focus on the scenario of someone joining the community. It groups different ways of contributing and resources of the community together. In particular, it collects the documentation concerning making code contribution to the project from the perspective of an outside contributor (others can use it too but the main audience will be partners making contributions to the core modules).
- Part of the gradual reorganization of the documentation (see documentation working group (DWG)).
- The initial emphasis of this reorg is the placement and navigation of content. Separate pass(es) will be done to focus on the content itself and best practices highlighted in the WG. What matters here is if we've collected legitimate existing content and framed it in a way that is clear for readers and writers of the documentation.
- What it looks like: https://fenekku.github.io/docs-invenio-rdm/community/
| @@ -103,12 +103,11 @@ When making your pull request, please keep the following in mind: | |||
| - Add tests and don't decrease test coverage. | |||
| - Add documentation. | |||
| - Follow our best practices: | |||
| - [Data migrations](../howtos/alembic.md) | |||
There was a problem hiding this comment.
My sense is that it's a maintainer that is more likely to deal with migrations, so it's not included in this section. It's more involved too, so it can be pushed deeper in the documentation.
| - [CSS/JS](css-js.md) and [React](react.md) | ||
| - [Web accessibility](accessibility.md) | ||
| - [User interface](ui.md) | ||
| - Identify the [copyright holder(s)](../../contribute/copyright-policy.md) and update copyright headers for touched files (>15 lines contributions). |
There was a problem hiding this comment.
Most changes are like this one: just involving path updates due to moving content around.
|
|
||
| ``` | ||
| ```bash |
There was a problem hiding this comment.
occasional slight improvement
|
|
||
| ### With GitHub CLI | ||
| === "With GitHub CLI" |
There was a problem hiding this comment.
Kind of experimentally snuck this one in. It tabs the content and makes the documentation much more compact / less daunting. It's only used here, but could be adopted for other sections.
| - CSS/JavaScript: develop/best-practices/css-js.md | ||
| - React: develop/best-practices/react.md | ||
| - User interface: develop/best-practices/ui.md | ||
| - Getting Started: |
There was a problem hiding this comment.
This section will eventually become the "Operate" section for how people running an instance can configure / customize / enhance it. Inevitably will require them to deal with virtual envs, debug and seek help ...
| @@ -281,6 +284,7 @@ markdown_extensions: | |||
| - pymdownx.highlight | |||
| - pymdownx.superfences | |||
| - pymdownx.critic | |||
|
|
|||
| - pymdownx.tabbed: | |||
There was a problem hiding this comment.
For the tabbed content highlighted in comment above.
fenekku
changed the title
| @@ -7,8 +7,7 @@ Find here important resources for onboarding. | |||
| ## For everyone | |||
| <!---* Mailing list (self-subscribe): https://lists.e-infra.cz/wws/info/project-inveniordm | |||
There was a problem hiding this comment.
Can the self-subscribe to the Mailing List be added back?
