updates

Author: rkdarst

content/index.rst

@@ -3,11 +3,7 @@ Aalto RSE training
 
 This site contains the Aalto RSE training program.  It's not a
 textbook, but a reference for use during mentoring and a reference for
-what the expectations are and where to read more.  The first half is
-what to expect at Aalto (not expected to be read all at once when
-starting, but slowly mentored).  The latter half is a collection of
-interesting reference links as RSEs are learning things, but also not
-intended to be followed one-for-one.
+what the expectations are and where to read more.  
 
 This site is under construction and "wiki rules" are in effect: if you
 see something, just make the update.  Someone will come later and
@@ -19,19 +15,25 @@ clean it up.
 
    what-is-a-rse
 
+General background information.
+
 .. toctree::
    :maxdepth: 1
    :caption: Roles
 
    roles/index
    roles/project-work
    roles/garage
-   roles/instructor
+   roles/teaching
    roles/planner
    roles/technical-mentor
    roles/unit-liaison
    roles/team-supervisor
 
+This section tells what to expect at Aalto.  It's not expected to be
+read all at once when starting, but slowly mentored according to each
+person's onboarding plan.
+
 .. toctree::
    :maxdepth: 1
    :caption: Project procedures
@@ -43,6 +45,9 @@ clean it up.
    tech
    it-in-aalto
 
+This section is a collection of interesting reference links as RSEs
+are learning things, but also not intended to be followed one-for-one.
+
 .. toctree::
    :maxdepth: 1
    :caption: Data management and open science
@@ -52,6 +57,11 @@ clean it up.
    ethics
    security
 
+This section also as a good reference for learning, but more about the
+broader picture than technology itself.  It's more worth everyone
+reading this.
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Other material

content/roles/garage.rst

@@ -7,7 +7,7 @@ Summary
 The "SciComp garage" is our daily office hour, where people can come
 and ask us anything.  Answering these questions is a quite demanding
 responsibility, and you need to be able to think on your feet and not
-get stressed.
+get stressed when you don't know something.
 
 Garage is not just a time to help others, but the common time we can
 talk with each other, and most importantly learn from each others'
@@ -18,15 +18,22 @@ can learn more.
 
 Main challenges/pitfalls
 ------------------------
-* You will often be asked things you don't know right away.  (Broad
-  solution: ask for more info in the way you would debug.  For
+* You will often be asked things you don't know right away.  (A broad
+  solution is: ask for more info in the way you would debug.  For
   example, start by asking to share the screen and show the exact
   problem).
-* You need to be able to know who else to refer people to.
+* You need to be able to know other people (ASC/RSE/ITS/research
+  services/etc.), to be able to refer customers to them when appropriate.
 * A lot like the "planner" role, you need to be able to understand
   lots of different things and advise on the best solution trade-off
   for each customer individually, without the time to take a break to
   plan.
+* Helping people while still giving them confidence that they can and
+  should keep trying themselves (and not over-playing your
+  confidence).
+* "Too many cooks" problem when too many staff try to support the
+  same person, simultaneously asking questions and giving
+  instructions.
 
 
 Expectations / checklists
@@ -37,12 +44,19 @@ Expectations / checklists
   However, attend often enough to stay connected to the team.
 * Treat all customers with the highest level of respect, regardless of
   their background or current experience level.
+* Make sure someone greets all incoming customers.
+* For each support case, make sure that one person (and not more than
+  one) is the primary communicator, to prevent the customer from
+  getting overloaded.
 * Ensure that you understand the full scope of the customer's request
   before diving in, especially the questions listed on
   :doc:`help/index` (has it ever worked?  what are you trying to
   accomplish?  what did you do?  what do you need?)
-* You may ask people to come back if you need more time to figure it
-  out, or you need a different person to be present.
+* When someone departs garage, give them encouragement to keep trying
+  themselves, that "yes this is hard, but you can do it".
+* You may ask people to come back another day (or schedule another
+  meeting) if you need more time to figure it out, or you need a
+  different person to be present.
 * Help as best you can and ask for help from others when needed.
 * Observe other answers so you can learn new things, and ask follow-up
   questions once the customers leave.

content/roles/index.rst

@@ -2,11 +2,16 @@ Roles intro
 ===========
 
 This section lists various roles and the training for them.  The roles
-are not formal and in practice everything is merged together.
-However, for the purposes of getting started slowly and not having to
+are not very formal and in practice everything gets blended together
+However, for the purposes of new people getting started and not having to
 learn everything all at once, it makes sense to try to classify them
 somehow.
 
+Everyone will take their own path to get started.  Teaching these
+roles is mainly (in 2026) via mentoring.  Everyone make take their own
+path.  Also note this material is a work in progress and will be
+developed along with the mentoring.
+
 
 Role list
 ---------
@@ -31,14 +36,14 @@ Role list
        they can be directed to other help (with advice).  Primary
        challenges include the huge variety of questions which may
        come, and the need to think on your feet.
-   * * Course instructor
-     * Teaches in courses, mainly using the CodeRefinery teaching
-       strategies of co-teaching, collaborative notes, and
-       livestreaming.  Teaches with compassion and always reminds
-       learners that stuff is actually difficult and people are not
-       alone.  Always maintains a critical mind about what should be
-       thought (as opposed to best practices that an instructor should
-       use).
+   * * Teaching
+     * Teaches (+other support) in courses, mainly using the
+       CodeRefinery teaching strategies of co-teaching, collaborative
+       notes, and livestreaming.  Teaches with compassion and always
+       reminds learners that stuff is actually difficult and people
+       are not alone.  Always maintains a critical mind about what
+       should be taught (as opposed to blindly recommending best
+       practices that aren't practical for the audienc).
    * * Project planner (architect?)
      * This person has enough broad experience to to untangle what the
        customer actually needs even when they may not know (or it may

content/roles/project-work.rst

@@ -29,40 +29,51 @@ Main challenges/pitfalls
 ------------------------
 
 * Working within a research group, without actually being part of it.
-* Maintaining close enough communication so that expectaions are met.
+* Maintaining close enough communication so that expectations are met.
+* Fully understanding what's going on and the expectations.
 * Gracefully handle major changes to the plan, possibly throwing
   everything off track.
 * Gracefully handle customers who have something else come up and thus
-  stop being responsive to us at all.
-
+  stop being responsive to us at all.  Figuring out what you should do
+  then: how to avoid it looking like you were inactive when they come
+  back (unless that is what was desired).
+* Not recording or being clear when the project goals drift.  Then
+  ending up at a point where we and the customer have different
+  expectations and are unhappy.
+* Customers who don't know as much about the project as you do
+  (managing their expectations, keeping them in the loop, etc.).
 
 
 Expectations / checklists
 -------------------------
 
-* When it's clear, negotiate and statr projects yourself
-* Use a researcher's mind and a developer's tools to solve
+* When the request is clear and you can do things without help,
+  negotiate and start projects yourself.  When it's complex, use the
+  ideas from :doc:`planner`.
+* Use a researcher's mind and a developer's tools to solve the
+  customer's problems.
 * Maintain active communication with the customers, especially making
-  sure that we avoid common pitfalls:
-
-  * Appearing inactive when the customers appear inactive
-  * Doing the wrong thing unexpectedly
-  * Customers don't know what's going on
-
+  sure that we avoid common pitfalls (see above)
 * Discuss frequently with your mentors to ensure that you stay on
-  track and they have the info to jump in if needed.
+  track and they have the info to intervene if it ever became needed.
 * Keep the customers up to date with what you are doing (for example
   at least weekly but ideally more), in a language customers can
   understand, in enough detail so that they can warn you if something
   is going wrong.
-
-* Ask for help when you need it
+* Ask for help when you need it.
 * Give a report in the RSE meeting once a project is done.
 
 
 External materials
 ------------------
 
+* :doc:`rse/procedures/project-administration`
+* :doc:`rse/procedures/prioritization`
+* Many other things on :doc:`rse/index`
+* `Timetracking via Gitlab procedures
+  <https://github.com/AaltoRSE/rse-timetracking/>`__
 
 Training program: materials and exercises
 -----------------------------------------
+
+Demonstration: going through the rse-projects gitlab tracker

content/roles/instructor.rst content/roles/teaching.rstcontent/roles/instructor.rst renamed to content/roles/teaching.rst

@@ -1,5 +1,5 @@
-Course instructor
-=================
+Teaching
+========
 
 Summary
 -------
@@ -10,13 +10,20 @@ bring projects into us.  When we see something that is taking up a lot
 of our support time, we can add it to our courses to save time
 long-term.
 
+Teaching isn't just being in front of people and talking, but there
+are very many parts to our collaborative teaching: co-teaching,
+collaborative notes, livestream broadcasting, lesson development,
+organizing courses, and more.
+
 
 Main challenges/pitfalls
 ------------------------
 
 * Getting use to the CodeRefinery teaching style (though once you are
   used to it, it's actually less work)
 * Managing time for lesson maintenance and development.
+* Teaching with the mindset of a learner (and what thy need to know),
+  not trying to teach them to be like you, an experienced RSE.
 
 
 Expectations / checklists
@@ -49,19 +56,20 @@ External materials
   (read the video description) by rkdarst
 * `Motivation to CodeRefinery instructor training
   <https://www.youtube.com/watch?v=61Cdi4Eje2Y>`__ by rkdarst
+  (includes ideas for teaching).
+* All :external+manuals:doc:`CodeRefinery manual pages <index>`
 
 
 Training program: materials and exercises
 -----------------------------------------
 
 * :doc:`instructor-intro`
 * :doc:`instructor-kickstart`
+* `CodeRefinery Train the Trainer <https://coderefinery.github.io/train-the-trainer/>`__
 
 
 Other
 -----
 
 * Course arrangement
-* What courses to recommend
 * Teaching philosophy
-* Livestream teaching

content/roles/unit-liaison.rst

@@ -33,7 +33,7 @@ Expectations / checklists
 * Stay in touch with the coordinators/leaders of the unit.
 * Where practical, go to the unit meetings and other events to
   represent the team.
-* Run :doc:`/help/group-meetings` for groups within the unit, or at
+* Run :doc:`help/group-meetings` for groups within the unit, or at
   least help arrange them and get others to come.
 
 

content/what-is-a-rse.rst

@@ -17,8 +17,20 @@ than typical research groups, and how we interact with research
 groups.  It's a much less individual role than an academic researcher,
 with different types of skills.
 
-What does "engineer" even mean?
+What does "engineer" even mean?  It's not just someone that knows some
+tools or practices.  It's someone who can balance the limits of
+technology, the needs of the customer, and broader costs (to the
+customer and society.  While a researcher can come up with ideas, and
+a developer can do the development they are asked to do, a RSE
+critically looks at the needs and comes up with the right solutions,
+taking into account the special needs and uncertainties of research.
 
+You should always keep in mind that we are here to help research and
+researchers, not technology.  This often means adapting the technology
+to what people actually need, not trying to force people to adapt to
+the technology.  We should give confidence to our customers to carry
+on by themselves after we are done.  We live and die by how our
+customers see us.
 
 What makes Aalto RSEs different from academic researches:
 
@@ -38,19 +50,17 @@ What makes Aalto RSE different from RSEs in other places:
   Our mission is much wider.
 
 
-* Help research and researchers
-  * We are also researchers
-  * Give confidence
-  *
-* Rescue from problems
-* Improve  scientific quality
-    * architect vs structural engineer
-* You don't have to know everything, just be good at explaining what you do know.
-
-
 
 Further reading
 ---------------
 
+* `Architects, engineers, and other infrastructure staff in
+  universities
+  <https://docs.google.com/presentation/d/1lF-2QtVa6obI_ceSYJ8wq0PhaiQVCf2Jmb_KUo6H-rQ>`__
+  by rkdarst.
+* `RSE lessons from Civil Engineering
+  <https://rkd.zgib.net/blog/rse-lessons-from-civil-engineering/>`__
+  by rkdarst
 * `A not-so-brief history of Research Software Engineers
   <https://www.software.ac.uk/blog/not-so-brief-history-research-software-engineers-0>`__
+* :doc:`rse/history`