Reorg

ProgressTrackingCards.md → 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.

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
 

SoftwareTeamInterviewerGuide.md → 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).

PSIP-Timeline.md → 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.