rse/: project management updates, first stage

Author: rkdarst

rse/checklists/project-done.rst

@@ -22,6 +22,7 @@ Discuss with the researchers
     entry can be made private or public, and the actual software/data
     is usually hosted elsewhere (and can be public or not).
 
+* Discuss long-term maintenance.
 * Discuss what to do if there are issues in the future - garage, issue
   tracker, training courses.
 * Discuss what else may (or may not) need doing in the future.
@@ -33,14 +34,23 @@ Internal (RSE group) tasks
 * Issue tracker:
 
   * ``/summary`` should contain a several sentence summary focused on the
-    benefit to RSE service (this is used for final reports, etc).
+    benefit to RSE service (this is used for final reports, etc).  A
+    single or few imperative sentences like a commit message, for
+    example "Port code to the LUMI supercomputer in order to allow
+    researchers to scale their work".
   * Confirm other metadata is correct
 
     * ``/contact``, ``/supervisor`` contains
       people who may get emails about the project later (and shouldn't
       contain people who may be surprised about automated survey
       emails).  If these people should not get
-    * ``/timesaved``
+    * ``/timesaved NN{h,d,mo}`` updated to include a rough estimate of
+      how much time was saved by the researcher, if you know.  If you
+      don't know, leave it blank.
+    * Use ``/estimate N{h,d,mo}`` to record the overall amount of time
+      you have spent (as in, as you get to the end, the estimate
+      should become pretty accurate).  (The defaults are taken from
+      size labels, G=1hr, S=2d, M=2w, L=2mo)
     * Outputs ``/projects``, ``/publications``, ``/software``,
       ``/datasets``, ``/outputs``
 
@@ -54,12 +64,11 @@ Internal (RSE group) tasks
   * Include a readme with citation, confirmation
     of what usage permissions there are, and a one-sentence general
     description suitable for presentations.
-  * Examples; screenshot of website, screenshot of code that looks
-    interesting, screenshot of repository page, picture of hardware
-    device used, etc.
+  * Examples: some figure generated, some equipment used, screenshot
+    of website, screenshot of code that looks interesting, screenshot
+    of repository page, picture of hardware device used, etc.
 
-* Add it to the next meeting agenda.  We will collaboratively do an
-  analysis to find lessons learned:
+* Add the project to the next meeting agenda for a lessons-learned discussion:
 
   * Facts about the project
   * Arrange facts into the big picture and timeline

rse/group-leaders.rst

@@ -1,5 +1,5 @@
-For group leaders
-=================
+Project management: PI perspective
+==================================
 
 You, or someone in your group, has requested :doc:`Research Software
 Engineer <../index>` services for one of your group's projects.  This
@@ -16,8 +16,8 @@ How it is funded
 There are two funding strategies:
 
 * Short term (a few weeks or less) is funded by your department, if
-  you are in one of the :doc:`sponsoring units <units>`.  You don't
-  need to do anything special.
+  you are in one of the :doc:`sponsoring units
+  <procedures/units-info>`.  You don't need to do anything special.
 * Longer term (month or more) is funded from your own projects.  See
   the information for :doc:`grant applicants <grant-applicants>`, it
   is also relevant if you already have funding you want to use.
@@ -29,6 +29,18 @@ There are two funding strategies:
 
 
 
+Project planning meeting
+------------------------
+
+We'll try to have a planning meeting to start the project at the
+beginning.  We'll talk about what needs to be done, what the goals
+are, who does what, risks and risk management, and long-term
+maintenance.  This should be written in some sort of shared doc that
+everyone can view and edit (ideally wherever your group normally
+stores such things, like OneDrive or Google Drive).
+
+
+
 Access to data and tools
 ------------------------
 
@@ -54,7 +66,8 @@ agreement that Aalto IT system administrators have, and are similarly
 vetted.
 
 Using our services doesn't affect your intellectual property right any
-more than another employee working on the project will.  This is
-service-for-pay, so you get all rights.  However, our RSEs expect to
-be acknowledged according to good scientific practice (see
-:doc:`how-we-work`).
+more than another employee working on the project will.  (In the event
+you don't plan for open science / open licenses, it should be planned
+first, though, to make sure everything gets taken care of.)  However,
+our RSEs expect to be acknowledged according to good scientific
+practice (see :doc:`how-we-work`).

rse/how-we-work.rst

@@ -1,60 +1,75 @@
-Starting a project with us
-==========================
+Project management: researcher perspective
+==========================================
 
-This page is mostly focused on how long-term scheduled projects, which
-are funded by the research groups themselves, work.
-**Long-term projects** are scheduled by fraction of full-time-equivalent
-(FTE) over weeks or months.
+This page describes the way that medium and long (week or longer)
+projects should be handled.
 
 For short-term code review tasks, come to any of our :doc:`garage
-sessions </help/garage>` and we will immediately take a look.
+sessions </help/garage>` and we will immediately take a look - no
+advance planning needed.  The garage is also the starting point to
+upgrading to a longer project.
 
 
 
-Types of service
-----------------
+Background
+----------
 
-* **Long-term** service deals with jobs that last months, and are
-  scheduled in terms of FTE percentage over months.  This is often
-  directly as salary from some grant, as a researcher would be.
+Short-term
 
-* **Medium-term** service deal with jobs scheduled in days.  This is
-  mostly funded by basic funding from the member units.
+.. figure:: https://github.com/AaltoSciComp/aaltoscicomp-graphics/blob/master/figures/project-steps.png?raw=true
+   :alt: A flowchart diagram, of which me main point is that you can
+	 request short-term "garage" support as much as you want, and
+	 it can get upgraded to a "project" if it's a big enough
+	 task.  The project should have a clear planning meeting in it
+	 and we'll verify that we have enough time before accepting.
 
-* **Short-term** usually consists of support at one of our
-  :doc:`garages </help/garage>` or a few hours of work.  This is
-  generally free (paid by unit basic funding).
+   Project management diagram.  The main point is short stuff is free
+   and easy in garage, and from garage we can upgrade to longer projects.
 
 
+Requesting
+~~~~~~~~~~
 
-Beginning
----------
+We encourage most people to request their initial support via the
+:ref:`SciComp Garage <scicomp-garage>`.  Really, almost no matter how
+you request, we'll ask you to drop by there some day to talk to us.
+If you request early, we might be able to do some advance preparation,
+but usually it's worth dropping by once to talk, and we can tell you
+what preparation is needed for a second meeting.
 
-To actually make a request for support, see :doc:`request`.
+For more info, see :doc:`request`.
 
 
-Initial meeting
-~~~~~~~~~~~~~~~
+
+Project planning meeting
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 First, you can expect an quick initial meeting between the researchers
-and RSEs.  Depending on the size and complexity of the project, there
-may be several to find the right RSE and ensure that we can do a good
-job helping you.
+and RSEs.  We'll go over the project and some of the main recurrent
+issues and try to handle them in advance.  Our `meeting template
+<https://docs.google.com/document/d/1XcxeNLRq0kOsFbDEmA7ArdbIrCVudMWHPFQsKRVcTIk/>`__
+goes over things we may ask.
+
+The first meeting should have whoever is actively working on it from
+the researcher side, possibly the supervisor, and at least two RSE
+staff to provide a wider perspective.
 
-* What scientific background knowledge is needed?  How long does it take to get
-  started?
+Things we may go over include:
+
+* What scientific background knowledge is needed?  How long does it
+  take to get started?
 * What type of contribution will the RSE make (see next section)?  For
-  purposes of
-  scientific integrity, consider if this reaches the point of
-  scientific authorship (see bottom).
-* Researchers: provide access to code, documentation, and relevant
-  scientific background in advance, so
-  that they can be browsed.  The more we know in advance, the better
-  we can estimate the time required and how to best help you.
+  purposes of scientific integrity, consider if this reaches the point
+  of scientific authorship (see bottom).
+* Researchers: If possible, provide access to code, documentation, and
+  relevant scientific background in advance, so that they can be
+  browsed.  The more we know in advance, the better we can estimate
+  the time required and how to best help you.
 * How do you manage your data?  To map things out, consider `this
   one-page data management plan table
   <https://drive.google.com/drive/folders/0BzlGN0F6ew2hc0hGVXVTaGZwQjQ>`__.
 * Final outputs, location, publication.
+* Risks and risk management
 * Time frame and schedule flexibility.
 
 
@@ -86,7 +101,7 @@ needs.  Together, we will think about these questions:
   - Prepare a project for publication, release, or being used by more
     people.
 
-- Future plan
+- Future plan and long-term maintenance
 
   - Primarily teach via example, so that the researcher can fully
     continue developing the project themselves.
@@ -120,23 +135,25 @@ project.
 If we schedule a project but lose contact with you (no responses to
 our messages), we'll assume you are busy with other things and may
 re-add the project to the queue, and we'll need to find a new time in
-the schedule.  Please let us know if you don't have time, we
-understand the busyness of research.
+the schedule.  In other words, we don't change for no-shows, but you
+may lose your place in the queue.  Please let us know if you don't
+have time, we understand the busyness of research.
 
 A project doesn't have to be done "all at once" but can be interleaved
-with your own work schedule.
-
+with your own work schedule.  In other words, we can work 25-50% for
+multiple months, as you may need.
 
 
 Costs and time tracking
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-We track the time we spend and record it to your project.
+We track the time we spend and record it to your project via Halli.
+The PI can track this progress.
 
 
 
-Getting started
----------------
+Typical concerns when getting started
+-------------------------------------
 
 Version control
 ~~~~~~~~~~~~~~~
@@ -163,20 +180,6 @@ period of refactoring to improve the existing code, where it seems
 like not much is getting done.  This is a necessary step in investing
 for the future.
 
-
-
-During the project
-------------------
-
-Our RSE will most likely want to go work with you, in your physical
-location (well, after corona-time), a lot of the time.  It would be
-good to arrange a desk area as close as possible to existing
-researchers.  "Mobile-space" but close is better than fixed but
-further.
-
-Our goal isn't just to provide a service, but to teach your group how
-to work better yourselves after the project.
-
 Software quality and testing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -192,6 +195,21 @@ software: you'll be using software much longer than you write it.  We
 aim for simple, reliable strategies rather than the fanciest things
 *right now*.
 
+
+
+
+During the project
+------------------
+
+As you may prefer, we can either work online or go visit you
+in-person, especially if you have convenient office space.  It would
+be good to arrange a desk area as close as possible to existing
+researchers.  "Mobile-space" but close is better than fixed but
+further.
+
+Our goal isn't just to provide a service, but to teach your group how
+to work better yourselves after the project.
+
 ..
   Overheads
   ~~~~~~~~~
@@ -210,22 +228,13 @@ aim for simple, reliable strategies rather than the fanciest things
   For short-term projects scheduled by hours, overhead isn't expected.
 
 
-
 After the project
 -----------------
 
 We don't want to drop support right after the project (that's why you
-work with us, not an external software developer).  Still, we have
-finite resources and can't fund work on one project from another, so
-can't do everything for everyone.  You can expect
-us to try to passively keep supporting you for during the "daily
-garage" time as best we can.
-
-If your department or unit provides basic funding (see the
-:doc:`implementation plan <procedures/implementation>`), then long-term service
-is included, and this has no limits.  However, this is shared among
-everyone in your unit, and focused on strategically support that helps
-many people.
+work with us, not an external software developer).  As best we can,
+you can keep coming to get help during the SciComp garage time, but
+you'll need to take a more active role.
 
 .. _rse-how-we-work-kpis:
 

rse/index.rst

@@ -15,7 +15,8 @@ For anything related to **custom software development, computational
 research, data management, workflow automation, scaling-up, deployment
 of public previews,
 collaborative work, reproducible research, optimization,
-high-performance computing, and more**, we can:
+high-performance computing, and more**, we can be the collaborator you
+need.  We can:
 
 * **Do it for you:** You need some custom technical
   software/solution.  We do it for you, you get straight to your work.
@@ -30,29 +31,31 @@ Instead of, or in addition to, hiring your own intern, postdoc,
 etc. to struggle with
 certain issues, we can help you. Our working groups consist of experienced
 researchers who have broad experience with scientific computing
-(programming, computing, data) for our academic work, and thus can
-seamlessly collaborate on research projects. We can also do
+in academic projects. We can also do
 consultation and training. You will have more
 impact since your work will become more reusable, open, and of a higher quality. We
 can work on your ongoing projects, or you can add us directly into your next
 grant application.
 
 .. _rse-history: https://www.software.ac.uk/blog/2016-08-17-not-so-brief-history-research-software-engineers-0
 
-**Service availability:** Garage support is available to researchers
-at Aalto.
-We serve projects from all Aalto schools thanks to IT Services grants,
-but our main funding currently comes from the School of Science.  For
-more information, see :doc:`procedures/units-info`.
+**Service availability:** Our daily help session :ref:`SciComp Garage
+<scicomp-garage>` is available to researchers at Aalto.  Medium-length
+projects (days--weeks) is available for "free" in proportion to our
+funding from various :doc:`units in proportion to their funding
+<procedures/units-info>`.  Longer projects (month+) should have their
+:doc:`own project funding <procedures/finance-practicalities>`.
 
 .. admonition:: Contact
 
-   For a quick chat to get started with any kind of project or request
-   any type of support, come to our :ref:`daily garage <scicomp-garage>`,
-   every workday online at 13:00.  Or
-   contact us by email at rse at aalto.fi, or fill out our
-   `request form <https://selfservice.esupport.aalto.fi/ssc/app#/order/2026/>`__.  See
-   :ref:`requesting RSE <request-rse>` for more.
+   It's best to talk live!  Come to our :ref:`online office hour ("SciComp
+   Garage") <scicomp-garage>` any workday at 13:00. You don't even
+   need a specific question; you can ask about a vague idea, if
+   we are even the right place to ask, or drop by to chat about your
+   experiences.  This is also how you would start a larger project
+   with us.
+
+   See :ref:`requesting RSE <request-rse>` for more including email.
 
 
 
@@ -105,6 +108,7 @@ Checklists
 .. toctree::
    :maxdepth: 1
 
+   Project starting template <https://docs.google.com/document/d/1XcxeNLRq0kOsFbDEmA7ArdbIrCVudMWHPFQsKRVcTIk>
    checklists/project-done
    checklists/python
    JOSS checklist (external) <https://joss.readthedocs.io/en/latest/review_checklist.html>
@@ -126,8 +130,8 @@ to improvement at any time.  Also see the :doc:`FCCI Tech
 .. toctree::
    :maxdepth: 1
 
-   procedures/templates
    procedures/project-administration
+   procedures/templates
    procedures/prioritization
    procedures/implementation
    procedures/job-descriptions