Latest spiral content, and revisions to documentation. (#38)

* Spiral 4 responsibility modeling (#19) (#36) * Add pointer to next spiral in previous spiral. * Initial document to start spiral 4. * Update summary for responsibility effort. * Checkpoint for the day. * Checkpoint - Still need to incorporate multi-def to ssp to def concept from vm interview. Add temporal concerns. * WIP: Research mapping model spiral 2 (#35) * Start Spiral 2 for mapping model enhancement change requests. * Create 2023-08-07.003.md Added @iMichaela input as spiral for model revisions. * Update README.md with spiral 3 * Update 2023-08-07.003.md with input from Michaela. * Update 2023-08-07.003.md Added one more reference. * Updated recommendations of 2023-08-07.003.md Updated recommendations of 2023-08-07.003.md to reflect comments and conclusions of each individual issue. --------- Co-authored-by: Michaela Iorga <[email protected]> * Update and simplify documentation. (#37) Initial pass at documentation update. --------- Co-authored-by: Michaela Iorga <[email protected]>
usnistgov · Aug 22, 2023 · 2630067 · 2630067
1 parent 4e23984
commit 2630067
Show file tree

Hide file tree

Showing 22 changed files with 2,034 additions and 296 deletions.
diff --git a/.github/ISSUE_TEMPLATE/initiate_spiral.yaml b/.github/ISSUE_TEMPLATE/initiate_spiral.yaml
@@ -0,0 +1,124 @@
+name: Problem Statement
+description: Please provide a statement of the problem to be considered for research.
+labels: ['Step 1 - Initiation']
+body:
+  - type: markdown
+    attributes:
+      value: A spiral must be in support of an approved research effort.  If a research effort has not started, you should start by creating a [problem statement issue](https://github.com/usnistgov/OSCAL-DEFINE/issues/new?assignees=&labels=Step+1+-+Initiation&projects=&template=problem_statement.yaml).
+
+
+
+  - type: input
+    id: github-research-effort
+    attributes:
+      label: OSCAL DEFINE Research Effort Link
+      description: Provide a link to the associated research effort issue.
+      placeholder: ""
+    validations:
+      required: true
+
+  - type: input
+    id: github-project
+    attributes:
+      label: GitHub Project Link
+      description: Typically, a spiral relates to an existing project.  OSCAL is the default below.
+      placeholder: https://github.com/usnistgov/OSCAL
+
+  - type: input
+    id: authors
+    attributes:
+      label: Author(s)
+      description: If you know the expected authors of this spiral, provide information below.
+      placeholder: Enter names here, if known.
+
+
+
+  - type: markdown
+    attributes:
+      value: The following fields should be completed **BEFORE** starting a spiral.
+
+  - type: textarea
+    id: focus
+    attributes:
+      label: Focus
+      description: Provide a few sentences that describe the focus of the spiral.
+    validations:
+      required: true
+
+  - type: textarea
+    id: requirements
+    attributes:
+      label: Requirements
+      description: Provide any scope, constraints or requirements that apply to this spiral.
+    validations:
+      required: true
+
+  - type: textarea
+    id: background
+    attributes:
+      label: Background
+      description: Provide a few sentences that describe any related background information for the spiral.
+    validations:
+      required: true
+
+  - type: markdown
+    attributes:
+      value: The following fields are typically completed **DURING** the spiral, and may be left blank.
+
+  - type: textarea
+    id: analysis
+    attributes:
+      label: Analysis
+      description: This should contain analysis of the outcome.
+    validations:
+      required: false
+
+  - type: textarea
+    id: recommendation
+    attributes:
+      label: Recommendation
+      description: This should contain recommendations related to the analysis.
+    validations:
+      required: false
+
+  - type: textarea
+    id: reference
+    attributes:
+      label: Reference
+      description: This should contain references related to the spiral.
+    validations:
+      required: false
+
+
+
+  - type: markdown
+    attributes:
+      value: The following fields are typically completed once information is available.
+
+  - type: input
+    id: current-spiral-sequence-number
+    attributes:
+      label: Current Spiral Sequence Number
+      description: You can leave this blank if a current number is not available.
+      placeholder: YYYY-MM-DD.001.md
+
+  - type: input
+    id: previous-spiral-sequence-number
+    attributes:
+      label: Previous Spiral Sequence Number
+      description: You can leave this blank if a previous number is not available.
+      placeholder: YYYY-MM-DD.001.md
+
+  - type: input
+    id: next-spiral-sequence-number
+    attributes:
+      label: Next Spiral Sequence Number
+      description: You can leave this blank if a next number is not available.
+      placeholder: YYYY-MM-DD.001.md
+
+
+
+
+
+
+
diff --git a/getting-started/facilitator/README.md → FACILITATOR_GUIDE.md b/getting-started/facilitator/README.md → FACILITATOR_GUIDE.md
diff --git a/README.md b/README.md
@@ -15,36 +15,42 @@ The output of each effort is:
 
 ## Process Overview
 
-**[An Example Research Effort with Spirals can be found here.](getting-started/GUIDED-TOUR.md)**
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/107055718/225630406-ab1a064d-5f5d-4053-b80f-7d1ae793f8cd.png">
+</p>
 
 ### Initiation
 
 - A problem, challenge or concern is identified, reviewed and prioritized for Discovery.
-
+- The threshold for this step is very low, and simply requires [opening an issue with a problem statement](https://github.com/usnistgov/OSCAL-DEFINE/issues/new?assignees=&labels=Step+1+-+Initiation&projects=&template=problem_statement.yaml).
+- Once an issue has been approved for a research effort, increments of work are ready to begin as a part of Discovery.
 ### Discovery (Spirals)
 
-- A research effort takes place in increments called spirals.
-
-<p align="center">
-  <img src="https://user-images.githubusercontent.com/107055718/225630406-ab1a064d-5f5d-4053-b80f-7d1ae793f8cd.png">
-</p>
+- A research effort takes place in increments called spirals.  
+- Each spiral:
+  - has an identified objective,
+  - and contributes to the understanding and/or solution to the problem statement.
 
 ### Explanation
 
-- At the end of Discovery, a formal presentation will be made.
+- Per Spiral:
+  - At the end of each Spiral, the information will be committed to the OSCAL DEFINE project.
+  - Findings will be presented for feedback and decision-making.
+  - When enough knowledge has been gained, a change request may be submitted or solution may begin development.  
+  - Spirals may continue to further define the solution or explore the problem further.
+- Per Research Effort, at the end of Discovery:
+  - The result may include a new or revised prototype, process or practice.
+  - The result should provide enough evidence to be used in engineering or practical application.
+
 
-## Getting Started
+## Participation
 
 - [Attend the OSCAL DEFINE Meetings](https://pages.nist.gov/OSCAL/contribute/define-meeting/)
 - [Review current research efforts](https://github.com/usnistgov/OSCAL-DEFINE/tree/main/research-2023)
-- [Open an issue with a problem statement](https://github.com/usnistgov/OSCAL-DEFINE/issues/new)
+- [Open an issue with a problem statement](https://github.com/usnistgov/OSCAL-DEFINE/issues/new?assignees=&labels=Step+1+-+Initiation&projects=&template=problem_statement.yaml)
 
 More documentation can be found in our [Getting Started](getting-started/) folder.  This will guide you through the process and provide information for conducting a successful, collaborative research effort.
 
-## Efforts as a series of Research Spirals
-
-> The process is inspired by [Boehm's *Spiral Model of Software Development and Enhancement*](https://ieeexplore.ieee.org/document/59) (with [a good overview in this video](https://www.youtube.com/watch?v=mp22SDTnsQQ)), but adapted to provide knowledge and decision support for new or enhanced OSCAL models.  A Spiral is an iterative, asynchronous effort that allows for research to begin with limited information, and delivers new discoveries and understanding at the end of each spiral.  This input guides ongoing efforts in research, which can in turn guide development activities.
-
 ---
 
 [usnistgov/OSCAL-DEFINE][gh-osr] is developed and maintained by the [NIST OSCAL Team][[email protected]], principally:
@@ -55,6 +61,8 @@ More documentation can be found in our [Getting Started](getting-started/) folde
 Please reach out with questions and comments.
 
 
+*This process is inspired by [Boehm's *Spiral Model of Software Development and Enhancement*](https://ieeexplore.ieee.org/document/59) (with [a good overview in this video](https://www.youtube.com/watch?v=mp22SDTnsQQ)), but adapted to provide knowledge and decision support for new or enhanced OSCAL models.  A Spiral is an iterative, asynchronous effort that allows for research to begin with limited information, and delivers new discoveries and understanding at the end of each spiral.  This input guides ongoing efforts in research, which can in turn guide development activities.*
+
 ---
 
 [gh-osr]: https://github.com/usnistgov/OSCAL-DEFINE/

diff --git a/getting-started/DEFINITIONS.csv b/getting-started/DEFINITIONS.csv
diff --git a/getting-started/GUIDED-TOUR.md b/getting-started/GUIDED-TOUR.md
diff --git a/getting-started/README.md b/getting-started/README.md
diff --git a/getting-started/research-topic-template/README.md b/getting-started/research-topic-template/README.md