Restructure docs.trr379.de #13
Loading…
Reference in a new issue
No description provided.
Delete branch "restructure"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
This PR does the initial restructuring as described in #12.
It also makes important updates to workflows that are regularly used by consortium members.
Particularly if you have experience working with the the current documentation, it would be great to hear your feedback on whether any information is unclear or missing.
I really appreciate the scale of the restructuring, and I think the updated documentation is nice to follow. As I'm the first to comment on the PR, I'll start with a few nitpicks. I suppose these aren't necessarily the things you changed now and could have been carried over from the earlier content, but these are the things that caught my eye.
@ -0,0 +10,4 @@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.{{% notice style="note" %}}To work on the website locally, you need SSH access to the TRR379 web server.This is no longer true, the Hub now only offers https, and it is sufficient also for annex pushes. Likewise, the clone URL below needs to change.
@ -0,0 +34,4 @@{{% notice style="important" %}}**Image requirements:** All images must be added using DataLad (`datalad save -m "message"`) or git-annex (`git annex add <file>`), and never with a plain `git add`.- Contributor portraits: maximum 400 pixels wideI'm not up to date, but there is a chance contributor portraits should now be uploaded via the Pool?
Good point - I moved these photo requirements to the workflow for creating a Person record in the pool to make it more clear that contributor photos shouldn't be uploaded via Forgejo.
@ -1,9 +1,9 @@---title: How to ...title: Using TRR379While I like the main title of the docs ("How to TRR379"), this one ("Using TRR379") reads a bit awkward to me. Maybe "Using TRR379 tools"?
@ -0,0 +23,4 @@5. Enter the DOI, and select "IMPORT". A new section should appear showing the imported metadata. If you receive an error message that the record already exists, follow the instructions to edit the existing record instead of importing a new one.{{% notice style="note" %}}Enter just the DOI without the URL project (i.e., `10.1016/j.neubiorev.2025.106386` and not `https://doi.org/10.1016/j.neubiorev.2025.106386`just the DOI without the URL project ==> just the DOI without the URL part
(alt. do not preface the entered identifier with the
doi.org/part), or similar@ -0,0 +17,4 @@### Manual requestIn order to obtain an account manually, email trr379@lists.fz-juelich.de. Please email from an institutional email, and CC the respective TRR379 project lead. In the email, mention any projects and/or or$ends abruptly with a dollar sign - and/or offer money? 😉
C/P error :) But I like the offer money option better ;)
@ -38,3 +38,3 @@Collected information is submitted to a TRR379-dedicated virtual server hosted at Forschunsgzentrum Jülich (operated by the [Q02 project](https://trr379.de/projects/q02)) via an encrypted connection.Collected information is submitted to a TRR379-dedicated virtual server hosted at Forschunsgzentrum Jülich (operated by the [Q02 project]({{% ref "/references/resources/projects/q02" %}}) via an encrypted connection.Individual person records are only accessible via a personalized link with an individual access token.Members receive this access information via email.A note to the future: The linked PDF-form under the following paragraph ("This service is opt-in. ...") does not exist anymore and will need an update for the 2026 survey.
@ -0,0 +1,43 @@---title: Platform GuidesNit: I'm not sure if I would classify all of the listed "services" (using the previous term for lack of a better one) as "platforms", and I'm also not sure if I would classify the individual pages as "guides".
If "Services" was ruled out, I feel like the term "Resources" or "Digital Resources" would fit a bit better, or maybe something like "Platform overview"?
I don't see any reason not to use "Services" -- changed it back.
@ -0,0 +3,4 @@weight: 10---This page is a more in-depth description of the rationale behind the [SOP]({{% ref "/references/terms/sop" %}}) for participant identifiers used by TRR379.This is just based on a gut feeling, but I wonder if the identifer concept for participants is important enough to warrant a more prominent position in the documentation hierarchy (one level up, directly under "Resources" would make it much more findable already, IMHO)? Also, (again, not sure, since I'm not working with TRR things at all), would it make sense to link the participant identifier section under the "work with raw mri data" section?
I moved it a level up as suggested under "Resources", but I'll leave it to @msz to decide if/where it should be linked to in the updated MRI data docs.
It could, but to be fair I am not sure how (maybe just a see-also admonition). The "work with MRI data" is now fairly high-level, it links to q02/heudiconv-container and q02/rdmtools/ and only there you would encounter identifiers.
Speaking of identifiers, there are some more discussions here all/status#20 and a bit more detailed here all/status#19 (comment), I don't think it's worth recording them in the docs, but it shows that there is more to the topic.
I've built the docs from this PR, including the changes proposed by @msz in #14, and I think its a big improvement!
I agree with the nits from @msz and his PR, I've added two small remarks as review comments.
One more general remark (not related to your changes, I just noticed when reading the docs in full): The docs use the phrase "contact Michael Hanke" a few times, and link to his profile on the website. That profile, however, does not immediately have contact information (people would probably click on the orcid record and find the hhu and fzj address, and I'm pretty certain that @mih never reads emails sent to his hhu address)
We just discussed it in the orga meeting and agreed that this version can be uploadd. So it would be great if someone could implement this change and upload the news I uploaded, so that we can circulate them and everyone can view the documents online. I will keep you updated if we then have a few more remarks.
Thank you, @msz for the MRI data docs, and to @a.wagner and @tseyrek for the reviews!
I have addressed these comments, apart from the how-to guide regarding the DFG survey, since it will be redone shortly anyways for the 2026 survey.
@ -0,0 +12,4 @@2. Log in using your preferred identity provider (i.e., GitHub or your affiliated organization via DFN-AAI SSO) and follow the on-screen instructions to activate your account.Please add a statement like
The underlying registeration ping/pong consumes a significant chunk of time admining the hub.
@a.wagner wrote in #13 (comment):
While I do see email, I totally agree that institutionalizing me as a communication bottleneck is not useful. Other places point out trr379@lists.fz-juelich.de as a contact point, and this should be done throughout.
There is no need to do this change within this PR.