Add contributing guide #17

Open
j.goddard wants to merge 3 commits from contributing into main
7 changed files with 74 additions and 2 deletions

View file

@ -0,0 +1,11 @@
---
title: Contributing
weight: 50
comment:
A place to collect workflows for how members can report, change, and edit things.
---
TRR379 infrastructure and its documentation and content are developed collaborately.
You can contribute by suggesting improvements and/or updating documentation and website content.
{{% children sort="weight" %}}

View file

@ -0,0 +1,48 @@
---
title: Contribute to the docs
weight: 10
---
Have you noticed that something in the documentation is missing or out-of-date?
If so, then we welcome your contributions, be it by [suggesting improvements](#suggest-improvements) or [editing the docs](#edit-the-docs) directly.
The sources for [this documentation]({{% ref "references/services/documentation" %}}) live on the [TRR379 Hub]({{% ref "references/services/collaboration-platform" %}}) at https://hub.trr379.de/q04/docs.trr379.de/src/branch/main.
## Suggest improvements
Please have a look at the [open issues](https://hub.trr379.de/q04/docs.trr379.de/issues) to see if your question/comment/discussion point has been brought up before.
If not, please [create a new issue](https://hub.trr379.de/q04/docs.trr379.de/issues/new) for discussion.
## Edit the docs
The documentation site is built with [Hugo](https://gohugo.io/) and stored as a [DataLad](https://www.datalad.org/) dataset.
1. [With DataLad installed](https://www.datalad.org/#install), clone the repository and then enter it:
`datalad clone https://hub.trr379.de/q04/docs.trr379.de.git`
`cd docs.trr379.de`
2. Download all content, including the theme:
`datalad get -r .`
3. Start the local preview server:
`hugo server`
4. After editing, push your changes:
`datalad push`
5. 5. **Alternatively:** {{% expand title="Make small edits directly on the collaboration hub." %}}
- The content of all pages can be browsed at https://hub.trr379.de/q04/docs.trr379.de/src/branch/main/content.
- Each page provides an edit button (pencil icon) that enables editing content directly in the browser.
{{% /expand %}}
{{% notice style="note" %}}
Once a change has been submitted, it is not reflected on the website immediately.
All changes are reviewed and possibly adjusted by members of the [Q02]({{% ref "/references/resources/projects/q02/" %}}) and [Q04]({{% ref "/references/resources/projects/q04/" %}}) teams.
{{% /notice %}}

View file

@ -1,11 +1,15 @@
--- ---
title: Edit the website title: Edit the website
weight: 10 weight: 20
--- ---
The [main TRR379 website]({{% ref "/references/services/main-website" %}}) is updated on a regular basis. The [main TRR379 website]({{% ref "/references/services/main-website" %}}) is updated on a regular basis.
Much of the content, including contributor and publication lists, updates automatically whenever member submit information through the [knowledge pooling tool]({{% ref "/references/services/knowledge-pooling/" %}}). Much of the content, including contributor and publication lists, updates automatically whenever member submit information through the [knowledge pooling tool]({{% ref "/references/services/knowledge-pooling/" %}}).
**Website updates should therefore happen through the metadata pooling system wherever possible.** **Website updates should therefore happen through the metadata pooling system wherever possible.**
If you would like to report an error, request an update, or start any other discussions related to the website, browse the [open issues](https://hub.trr379.de/q04/www.trr379.de/issues);
if your discussion point is *not* already listed, please [open a new issue](https://hub.trr379.de/q04/www.trr379.de/issues/new).
For those who need to edit the website directly (e.g., to add news items), the site is built with Hugo and stored as a DataLad dataset, meaning all changes are version-controlled. For those who need to edit the website directly (e.g., to add news items), the site is built with Hugo and stored as a DataLad dataset, meaning all changes are version-controlled.
The [repository README](https://hub.trr379.de/q04/www.trr379.de#readme) contains instruction on how to obtain a clone of the website for working on it, and testing it locally. The [repository README](https://hub.trr379.de/q04/www.trr379.de#readme) contains instruction on how to obtain a clone of the website for working on it, and testing it locally.
@ -43,3 +47,4 @@ Page thumbnails should be a minimum of 320 by 240 pixels with an aspect ratio of
Once a change has been submitted, it is not reflected on the website immediately. Once a change has been submitted, it is not reflected on the website immediately.
All changes are reviewed and possibly adjusted by the website editor team of the [Q04]({{% ref "/references/resources/projects/q04/" %}}). All changes are reviewed and possibly adjusted by the website editor team of the [Q04]({{% ref "/references/resources/projects/q04/" %}}).
{{% /notice %}} {{% /notice %}}

View file

Before

Width:  |  Height:  |  Size: 66 B

After

Width:  |  Height:  |  Size: 66 B

Before After
Before After

View file

@ -5,3 +5,10 @@ weight: 90
https://docs.trr379.de (this site) is the main documentation source for the TRR379. https://docs.trr379.de (this site) is the main documentation source for the TRR379.
It offers information on facilities and procedures. It offers information on facilities and procedures.
It sources live on the [collaboration platform]({{% ref "references/services/collaboration-platform" %}}) at https://hub.trr379.de/q04/docs.trr379.de and are stored as a [DataLad](https://www.datalad.org/) dataset.
The documentation website is built with the [Hugo](https://gohugo.io/) static website generator.
Content of the pages is written in [Markdown](https://daringfireball.net/projects/markdown/).
For information on contributing to the docs, see:
- [Contribute to the docs]({{% ref "contributing/docs-update" %}})

View file

@ -16,6 +16,7 @@ Follow the links below for details on each platform and how you can get set up.
- The [TRR379 space on **Matrix**]({{% ref "/references/services/matrix/" %}}) is an informal place to connect with other members, exchange information, and get faster feedback. - The [TRR379 space on **Matrix**]({{% ref "/references/services/matrix/" %}}) is an informal place to connect with other members, exchange information, and get faster feedback.
- The [**`all/status` repository**](https://hub.trr379.de/all/status/issues) on the [Hub]({{% ref "/references/services/collaboration-platform" %}}) is a place to collect all issues related to TRR379 data integration. - The [**`all/status` repository**](https://hub.trr379.de/all/status/issues) on the [Hub]({{% ref "/references/services/collaboration-platform" %}}) is a place to collect all issues related to TRR379 data integration.
- There is a bi-weekly **office hours** for TRR379 members to connect synchronously. For more information on timing and how to join, see the [Office Hours section on the Support page]({{% ref "support/#office-hours" %}}).
### Report research activity ### Report research activity

View file

@ -1,6 +1,6 @@
--- ---
title: Support title: Support
weight: 50 weight: 40
comment: comment:
A place to collect details on where consortium members can turn to get support. A place to collect details on where consortium members can turn to get support.
--- ---