From cba2afbfb72184ac6765ede46f38d45439c462c4 Mon Sep 17 00:00:00 2001 From: "Elsa Gonsiorowski (Uranus)" Date: Thu, 17 Jan 2019 09:53:14 -0800 Subject: [PATCH 1/5] moved all PTC stuff into one place --- {src/PTCs => PTCs}/CoverageTestingPractice.pptx | Bin ProgressTrackingCards.md => PTCs/README.md | 0 {src/PTCs => PTCs}/SourceManagementPractice.pptx | Bin {src/PTCs => PTCs}/UnitTestingExample.pptx | Bin 4 files changed, 0 insertions(+), 0 deletions(-) rename {src/PTCs => PTCs}/CoverageTestingPractice.pptx (100%) rename ProgressTrackingCards.md => PTCs/README.md (100%) rename {src/PTCs => PTCs}/SourceManagementPractice.pptx (100%) rename {src/PTCs => PTCs}/UnitTestingExample.pptx (100%) diff --git a/src/PTCs/CoverageTestingPractice.pptx b/PTCs/CoverageTestingPractice.pptx similarity index 100% rename from src/PTCs/CoverageTestingPractice.pptx rename to PTCs/CoverageTestingPractice.pptx diff --git a/ProgressTrackingCards.md b/PTCs/README.md similarity index 100% rename from ProgressTrackingCards.md rename to PTCs/README.md diff --git a/src/PTCs/SourceManagementPractice.pptx b/PTCs/SourceManagementPractice.pptx similarity index 100% rename from src/PTCs/SourceManagementPractice.pptx rename to PTCs/SourceManagementPractice.pptx diff --git a/src/PTCs/UnitTestingExample.pptx b/PTCs/UnitTestingExample.pptx similarity index 100% rename from src/PTCs/UnitTestingExample.pptx rename to PTCs/UnitTestingExample.pptx From ad50275614aeb4cbaec8764740849311902b3903 Mon Sep 17 00:00:00 2001 From: "Elsa Gonsiorowski (Uranus)" Date: Thu, 17 Jan 2019 09:54:43 -0800 Subject: [PATCH 2/5] moved interview stuff together --- .../IntroductoryLetterTemplate.md | 0 .../IntroductoryLetterTemplate2.md | 0 .../SoftwareTeamInterviewTemplate.md | 0 .../SoftwareTeamInterviewerGuide.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename IntroductoryLetterTemplate.md => interviews/IntroductoryLetterTemplate.md (100%) rename IntroductoryLetterTemplate2.md => interviews/IntroductoryLetterTemplate2.md (100%) rename SoftwareTeamInterviewTemplate.md => interviews/SoftwareTeamInterviewTemplate.md (100%) rename SoftwareTeamInterviewerGuide.md => interviews/SoftwareTeamInterviewerGuide.md (100%) diff --git a/IntroductoryLetterTemplate.md b/interviews/IntroductoryLetterTemplate.md similarity index 100% rename from IntroductoryLetterTemplate.md rename to interviews/IntroductoryLetterTemplate.md diff --git a/IntroductoryLetterTemplate2.md b/interviews/IntroductoryLetterTemplate2.md similarity index 100% rename from IntroductoryLetterTemplate2.md rename to interviews/IntroductoryLetterTemplate2.md diff --git a/SoftwareTeamInterviewTemplate.md b/interviews/SoftwareTeamInterviewTemplate.md similarity index 100% rename from SoftwareTeamInterviewTemplate.md rename to interviews/SoftwareTeamInterviewTemplate.md diff --git a/SoftwareTeamInterviewerGuide.md b/interviews/SoftwareTeamInterviewerGuide.md similarity index 100% rename from SoftwareTeamInterviewerGuide.md rename to interviews/SoftwareTeamInterviewerGuide.md From 4b53882ca26589d34845cf659098b2d23d776352 Mon Sep 17 00:00:00 2001 From: "Elsa Gonsiorowski (Uranus)" Date: Thu, 17 Jan 2019 09:56:23 -0800 Subject: [PATCH 3/5] moved process stuff together --- PSIP-Overview.md => process/PSIP-Overview.md | 0 PSIP-Timeline.md => process/PSIP-Timeline.md | 0 SwPspWorkflow.jpg => process/SwPspWorkflow.jpg | Bin {src => process}/SwPspWorkflow.pptx | Bin 4 files changed, 0 insertions(+), 0 deletions(-) rename PSIP-Overview.md => process/PSIP-Overview.md (100%) rename PSIP-Timeline.md => process/PSIP-Timeline.md (100%) rename SwPspWorkflow.jpg => process/SwPspWorkflow.jpg (100%) rename {src => process}/SwPspWorkflow.pptx (100%) diff --git a/PSIP-Overview.md b/process/PSIP-Overview.md similarity index 100% rename from PSIP-Overview.md rename to process/PSIP-Overview.md diff --git a/PSIP-Timeline.md b/process/PSIP-Timeline.md similarity index 100% rename from PSIP-Timeline.md rename to process/PSIP-Timeline.md diff --git a/SwPspWorkflow.jpg b/process/SwPspWorkflow.jpg similarity index 100% rename from SwPspWorkflow.jpg rename to process/SwPspWorkflow.jpg diff --git a/src/SwPspWorkflow.pptx b/process/SwPspWorkflow.pptx similarity index 100% rename from src/SwPspWorkflow.pptx rename to process/SwPspWorkflow.pptx From 3cd635287ec727fe43c2e6e925e8752dbaf595fd Mon Sep 17 00:00:00 2001 From: "Elsa Gonsiorowski (Uranus)" Date: Thu, 17 Jan 2019 10:00:49 -0800 Subject: [PATCH 4/5] info policy is for interviews --- PSIPInformationPolicy.md => interviews/PSIPInformationPolicy.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename PSIPInformationPolicy.md => interviews/PSIPInformationPolicy.md (100%) diff --git a/PSIPInformationPolicy.md b/interviews/PSIPInformationPolicy.md similarity index 100% rename from PSIPInformationPolicy.md rename to interviews/PSIPInformationPolicy.md From f7f450c6ce4193b848c97090d5864afbbd1829c7 Mon Sep 17 00:00:00 2001 From: "Elsa Gonsiorowski (Uranus)" Date: Thu, 17 Jan 2019 10:05:52 -0800 Subject: [PATCH 5/5] fixed up the links --- PTCs/README.md | 8 ++++---- README.md | 12 ++++++------ interviews/SoftwareTeamInterviewerGuide.md | 15 +++++++-------- process/PSIP-Timeline.md | 10 +++++----- 4 files changed, 22 insertions(+), 23 deletions(-) diff --git a/PTCs/README.md b/PTCs/README.md index d9ee197..f9d698d 100644 --- a/PTCs/README.md +++ b/PTCs/README.md @@ -1,6 +1,6 @@ # Progress Tracking Cards -An essential aspect of the PSIP process is defining goals and tracking progress. A Progress Tracking Cards (PTC) is a brief structured document that lists concrete steps toward a specific productivity and sustainability goal. +An essential aspect of the PSIP process is defining goals and tracking progress. A Progress Tracking Cards (PTC) is a brief structured document that lists concrete steps toward a specific productivity and sustainability goal. ### Pre-requisites @@ -16,6 +16,6 @@ PTC values are meant to be ordinal, not cardinal. In other words, the values ar ### PTC Examples -- [Coverage Testing Template:](PTCs/CoverageTestingPractice.jpg) [[PPTX Source]](src/PTCs/CoverageTestingPractice.pptx) Sample card template for a team wanting to improve the fraction of its code that is tested. Statements should be customized and made precise for the team's goals. -- [Source Management Template:](PTCs/SourceManagementPractice.jpg) [[PPTX Source]](src/PTCs/SourceManagamentPractice.pptx) Sample card template for a team wanting to introduce or improve source code management. Statements should be customized and made precise for the team's goals. -- [Unit Testing Example:](PTCs/UnitTestingExample.jpg) [[PPTX Source]](src/PTCs/UnitTestingExample.pptx) Example card taken from a project where the team was starting a refactoring effort and wanted to establish a comprehensive and sustainable unit testing capability. +- [Coverage Testing Template:](CoverageTestingPractice.jpg) [[PPTX Source]](CoverageTestingPractice.pptx) Sample card template for a team wanting to improve the fraction of its code that is tested. Statements should be customized and made precise for the team's goals. +- [Source Management Template:](SourceManagementPractice.jpg) [[PPTX Source]](SourceManagamentPractice.pptx) Sample card template for a team wanting to introduce or improve source code management. Statements should be customized and made precise for the team's goals. +- [Unit Testing Example:](UnitTestingExample.jpg) [[PPTX Source]](UnitTestingExample.pptx) Example card taken from a project where the team was starting a refactoring effort and wanted to establish a comprehensive and sustainable unit testing capability. diff --git a/README.md b/README.md index 8dd064f..2a7c4f6 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ ### Productivity and Sustainability Improvement Planning (PSIP) Tools -This repository contains a collection of documents that support an iterative planning process for improving scientific software developer productivity and product sustainability through improved software practices, processes and tools. +This repository contains a collection of documents that support an iterative planning process for improving scientific software developer productivity and product sustainability through improved software practices, processes and tools. #### Key Repository Documents -- [PSIP Information Policy:](PSIPInformationPolicy.md) This document describes how we will handle information collected from software teams, with the intent to enable trusted conversations. -- [Overview of the PSIP Process:](PSIP-Overview.md) This document provides and overview of PSIP and a step by step description of how to execute the planning process. -- [Interviewer Guide:](SoftwareTeamInterviewerGuide.md) The PSIP process starts with a team interview, where a brief sketch of a team's software activies are gathered. This sketch serves as the foundation for subsequent practice improvement efforts. -- [Interview Template:](SoftwareTeamInterviewTemplate.md) This document contains a set of interview prompts that facilitate discusion and recording of a team's current approach to software product development. It is written in plain language to facilitate an accessible discussion and to avoid misuse and lack of understanding that can come from using formal software engineering terms that may not be well or consistently understood. -- [Progress Tracking Card (PTC) Construction Guide:](ProgressTrackingCards.md) This document gives some background on the philosophy and structure of PTCs, and instructions for how to construct a good PTC. +- [PSIP Information Policy:](interviews/PSIPInformationPolicy.md) This document describes how we will handle information collected from software teams, with the intent to enable trusted conversations. +- [Overview of the PSIP Process:](process/PSIP-Overview.md) This document provides and overview of PSIP and a step by step description of how to execute the planning process. +- [Interviewer Guide:](interviews/SoftwareTeamInterviewerGuide.md) The PSIP process starts with a team interview, where a brief sketch of a team's software activies are gathered. This sketch serves as the foundation for subsequent practice improvement efforts. +- [Interview Template:](interviews/SoftwareTeamInterviewTemplate.md) This document contains a set of interview prompts that facilitate discusion and recording of a team's current approach to software product development. It is written in plain language to facilitate an accessible discussion and to avoid misuse and lack of understanding that can come from using formal software engineering terms that may not be well or consistently understood. +- [Progress Tracking Card (PTC) Construction Guide:](PTCs/README.md) This document gives some background on the philosophy and structure of PTCs, and instructions for how to construct a good PTC. #### PSIP Training diff --git a/interviews/SoftwareTeamInterviewerGuide.md b/interviews/SoftwareTeamInterviewerGuide.md index 1f473b9..cd947f8 100644 --- a/interviews/SoftwareTeamInterviewerGuide.md +++ b/interviews/SoftwareTeamInterviewerGuide.md @@ -34,27 +34,27 @@ As you conduct the interview, assess if you have missed any of these basic discu #### **Software Development** -1. How software requirements are determined and transformed into implemented code, tested and deployed (the software lifecycle), +1. How software requirements are determined and transformed into implemented code, tested and deployed (the software lifecycle), -2. How integration of new and revised capabilities into the existing software will preserve existing capabilities (regression testing), +2. How integration of new and revised capabilities into the existing software will preserve existing capabilities (regression testing), 3. How users will learn about utilizing the code in their scientific efforts (documentation and training). **Tools** -1. Source management tools and processes (how source code will be developed and managed), +1. Source management tools and processes (how source code will be developed and managed), -2. Issue tracking tools and processes (how feature requests and software faults or "bugs" will be recorded and managed), +2. Issue tracking tools and processes (how feature requests and software faults or "bugs" will be recorded and managed), 3. Regression testing tools and processes (how regression tests will be invoked), 4. Software distribution tools and processes (how will users and collaborators access software products). -#### **Software used but not developed (a.k.a, third-party software):** +#### **Software used but not developed (a.k.a, third-party software):** Use of third-party software typically reduces the cost (time and effort) compared to developing the same capability independently. At the same time, it also increases risk. If the project makes significant use of scientific software developed by others, the following requirements should be addressed: - + 1. Describe how the third-party software is tested for correct behavior, initially and when upgrading to a new version (verification and validation). @@ -86,5 +86,4 @@ Use of third-party software typically reduces the cost (time and effort) compare 1. The shepherd stays in regular contact with the software team. -2. The shepherd and the software team execute a complete PSIP iteration as sketch in the [PSIP Timeline document](PSIP-Timeline.md). - +2. The shepherd and the software team execute a complete PSIP iteration as sketch in the [PSIP Timeline document](../process/PSIP-Timeline.md). diff --git a/process/PSIP-Timeline.md b/process/PSIP-Timeline.md index 0f7b79d..0450ae9 100644 --- a/process/PSIP-Timeline.md +++ b/process/PSIP-Timeline.md @@ -1,6 +1,6 @@ ## Target Timeline for Executing the PSIP Process -PSIP is an iterative process where each iteration may take weeks or months to complete. This document describes a suggested timeline and issues to consider when applying PSIP to a specific project. +PSIP is an iterative process where each iteration may take weeks or months to complete. This document describes a suggested timeline and issues to consider when applying PSIP to a specific project. Roles in the process are: - **Software Team:** The group of people developing a software product and using PSIP to improve software practices. @@ -10,17 +10,17 @@ Roles in the process are: We use the START label to indicate the date when the interview and software team meet to create or revise the Software Practices Document (Step one in the [PSIP workflow diagram](SwPspWorkflow.jpg)). Other times are given relative to this date in number of weeks. -### Timeline +### Timeline The following table shows target dates **in weeks** relative to START for each phase. For example, if the start date is June 28, `-2` in the Date column is June 14. Additional columns list who is involved and provide a brief description of activities. | Phase | Date | Participants | Activity | |:-------------: |:-----: |:---------------:|----------| -| **Invitation** | - 4 weeks | Interview Lead | Send an invitation to the software project team. Point them to the PSIP Overview. A [Letter Template](IntroductoryLetterTemplate.md) is available. Include a link to the [Information Policy](PSIPInformationPolicy.md) in the invitation. +| **Invitation** | - 4 weeks | Interview Lead | Send an invitation to the software project team. Point them to the PSIP Overview. A [Letter Template](../interviews/IntroductoryLetterTemplate.md) is available. Include a link to the [Information Policy](../PSIPInformationPolicy.md) in the invitation. | **PSIP Preparation** | - 3 weeks | Interview Lead | If you receive a positive response, send the software team a link to the [PSIP Overview](PSIP-Overview.md), asking them to review it and identify questions they may have prior to the interview. -| **Plan the Interview** | -2 weeks | All | Determine participants: Who will lead the interview, who will take notes, who will lead responses from the software team. Send out meeting participation information (room, video or teleconference). Review the [PSIP Interviewers Guide](SoftwareTeamInterviewerGuide.md). +| **Plan the Interview** | -2 weeks | All | Determine participants: Who will lead the interview, who will take notes, who will lead responses from the software team. Send out meeting participation information (room, video or teleconference). Review the [PSIP Interviewers Guide](../interviews/SoftwareTeamInterviewerGuide.md). | **Pre-Interview Check** | - 1 week | Interview Lead | Contact software project team asking if there are questions about the PSIP scope and preparations. -| **Interview** | START | All | Conduct interview using the [PSIP process](README.md). Make sure that all expected outcomes from the interview are completed. Set date for first follow up, which should be in about a week. +| **Interview** | START | All | Conduct interview using the [PSIP process](../README.md). Make sure that all expected outcomes from the interview are completed. Set date for first follow up, which should be in about a week. | **First Follow-up** | + 1 | Shepherd, software team | Contact software team to check on progress toward creating productivity improvement plan and progress tracking cards. | **Second Follow-up** | + 4 | Shepherd, software team | Contact software team to check on progress toward improving selected practices, identify any impediments and requests for information to improve progress tracking scores. | **Complete PSIP Goals** | + 8 | Software team | Software team completes practice improvement goals established in their plan.