search

esciencecenter-digital-skills / research-software-support

Content for the Research Software Support platform
https://esciencecenter-digital-skills.github.io/research-software-support/
Other
3 stars 3 forks source link

First draft of documentation module structure #31

Closed paulmaxus closed 1 month ago

paulmaxus commented 5 months ago

We added a first draft for this module structure with slides, intro and an additional exercise. We are addressing some points under issue #7 here, e.g. the division into user, developer and contributor documentation.

paulmaxus commented 5 months ago

Nice work @paulmaxus!

I feel like this still needs some love, especially in making it one coherent story. There are now a few different categorisations of documentation (mainly into user/developer and tutorial/how-to/explanation/reference) that partly overlap and this would really confuse the learner.

Maybe it makes sense to update the little design in #7 (comment) and from there put it all together with this one flow in mind. And then keep in mind that less is more. Especially in teaching about documentation which is a topic that is IMO more about bringing across a certain attitude than actual skills or knowledge.

What is the next step? Will you work on this further @paulmaxus ?

Totally, I might have some time tomorrow to continue. And yes, I think we should go back to the original issue and start from there. It might make sense to schedule a call at some point to untangle what we have so far and how to proceed from here.

svenvanderburg commented 5 months ago

@paulmaxus yeah would be cool if you can update the 'design' in #7 and then we can have a short call to align. You can try to book a meeting with me here

svenvanderburg commented 4 months ago

@paulmaxus yeah would be cool if you can update the 'design' in #7 and then we can have a short call to align. You can try to book a meeting with me here

@paulmaxus do you have time to meet about this? Let's try to get a working version of this module out and open new issues for remaining tasks.

JaroCamphuijsen commented 4 months ago

@svenvanderburg @paulmaxus I am planning some new sprints in the coming months. First one (will be mainly internal, but you can definitely join if you are free) is next week 28th and 29th of May, the next is 11th and 12th of May and I will actively invite more external/non-eScience-center people. Perhaps both of you can join one of these sprints?

svenvanderburg commented 4 months ago

@JaroCamphuijsen I cannot join next week, but could join 11th of June (if that is what you mean instead of May, but maybe you are indeed planning a sprint in the past)

paulmaxus commented 4 months ago

Sorry for replying so late! I won't be able to join the upcoming session, but hope to work on it again later this summer.

raar1 commented 1 month ago

Thanks everyone who has worked on this PR so far. As we will be teaching the course in around 1 month, I am going to try to quickly get this into a complete module today. I can't work on Max's personal branch directly so I will merge what is here into the existing https://github.com/esciencecenter-digital-skills/research-software-support/tree/documentation-module branch and continue work there. I will also try to address the issues I see that have been raised in the discussion above.

raar1 commented 1 month ago

Anyone looking for the new PR (module updated to work with new versions of NEBULA) can find it here: #104