Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Develop implementer documentation for OSCAL GitHub #110

Closed
akarmel opened this issue Feb 20, 2018 · 16 comments
Closed

Develop implementer documentation for OSCAL GitHub #110

akarmel opened this issue Feb 20, 2018 · 16 comments
Assignees
@anweiss @kscarf1
Labels
LoE: Medium User Story
Milestone
OSCAL 1.0 Milesto...

Comments

@akarmel
Copy link
Contributor

akarmel commented Feb 20, 2018

As an implementer, I would like detailed, clear and concise documentation on how I can use OSCAL in my organization.

Goals:
Develop detailed, clear and concise documentation for OSCAL implementers as started in issue #58

Dependencies:
Stable catalog model

Acceptance Criteria:
Detailed, clear and concise documentation for OSCAL implementers is available.
@akarmel akarmel mentioned this issue Feb 20, 2018
Closed
@kscarf1 kscarf1 assigned kscarf1 and unassigned kscarfone Feb 21, 2018
@akarmel
Copy link
Contributor Author

akarmel commented Mar 1, 2018

Sprint 8 Progress Notes

  • Karen will reach out to Andrew and Dave to setup a call to discuss this issue
    • Goal is to develop a punch list of what needs to be done

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 2, 2018

Emailed Andrew and Dave to set up a call for Monday.

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 5, 2018

We couldn't find a time on Monday that worked for all of us. Expecting to talk Tuesday instead.

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 6, 2018

We spoke this morning, and Andrew has transferred all the in-progress documentation to the slate branch. I will continue to work on it there.

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 8, 2018

I have completed a first draft of initial documentation on OSCAL usage.

@akarmel
Copy link
Contributor Author

akarmel commented Mar 8, 2018

Sprint 8 Acceptance

  • CONTRIBUTORS.MD is complete
  • Need to carry this issue forward to Sprint 9 to develop IMPLEMENTERS.MD and ROADMAP.MD (or appropriate hierarchical format in Slate)

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 11, 2018

Based on plans documented in issue #58 comments, the IMPLEMENTERS.MD page was supposed to be the main documentation page for catalog and profile maintainers, and tool vendors. It was going to link to the high-level OSCAL model, the OSCAL document model and tagging specification, OSCAL examples, etc. That's ended up being developed through the Slate-provided page structure. The source/index.html.md page includes the high-level model, and there are separate pages explaining the tags and showing examples. So I'm not sure if we need an IMPLEMENTERS.MD any more, if it should just be a file that points to all these other files, or if it needs other content that we hadn't previously planned on.

Regarding ROADMAP.MD, there's already a basic page there. I need to update the graphic based on the latest model.

@akarmel
Copy link
Contributor Author

akarmel commented Mar 15, 2018 •
edited
Loading

3/15/2018 - Sprint 9 Progress Notes

  • Need to develop implementers documentation through the Slate-provided page structure
    • Karen will create an IMPLEMENTERS.MD file and place it in the includes directory for inclusion into the Slate-provided page structure
  • ROADMAP.MD needs to be updated leveraging the RSA content

@akarmel akarmel mentioned this issue Mar 15, 2018
Closed
@kscarf1
Copy link
Contributor

kscarf1 commented Mar 22, 2018 •
edited
Loading

I have updated the ROADMAP.MD equivalent to use the RSA diagram. The file is at https://github.com/wendellpiez/OSCAL/blob/docs/source/roadmap/index.html.md.

@akarmel
Copy link
Contributor Author

akarmel commented Mar 22, 2018

3/22/2018 - Sprint 9 Progress Notes

@kscarf1
Copy link
Contributor

kscarf1 commented Mar 29, 2018

Wendell, Dave, Andrew, and I met to discuss documentation workflow. I will be completing the documentation for implementers (producers) in preparation for deployment to pages.nist.gov. The documentation will be ready in draft format by Wednesday, April 4th for review and discussion during the Thursday weekly call. This will give us time to finalize the documentation before publication to pages.nist.gov.

@kscarf1 kscarf1 mentioned this issue Mar 29, 2018
Closed
@akarmel
Copy link
Contributor Author

akarmel commented Mar 29, 2018

3/29/2018 - Sprint 9 Progress Notes

  • See Karen's progress note above
  • Will review the documentation during next Thursday's status meeting
  • DECISION: OSCAL Consumers and Producers will be treated the same as opposed to as separate audiences...will develop one uniform set of documentation
  • DECISION: Documentation will be produced outside the standard OSCAL Documentation Workflow pipeline as the pipeline is still in development

@kscarf1
Copy link
Contributor

kscarf1 commented Apr 3, 2018

With the new approach (one set of documentation for both consumers and producers), separate implementer documentation is no longer needed. I've deleted the blank IMPLEMENTERS.MD file and am reviewing all other documentation to remove any references to only consumers or producers.

david-waltermire added a commit that referenced this issue Apr 3, 2018
@david-waltermire
# This is a combination of 29 commits.
5b13d9d 
# The first commit's message is:

# This is a combination of 54 commits.
# The first commit's message is:

# This is a combination of 4 commits.
# The first commit's message is:

# This is a combination of 2 commits.
# The first commit's message is:

# This is a combination of 2 commits.
# The first commit's message is:

# This is a combination of 6 commits.
# The first commit's message is:

# This is a combination of 3 commits.
# The first commit's message is:

# This is a combination of 111 commits.
# The first commit's message is:

Initial commit of docs branch.

# This is the commit message #2:

Create CONTRIBUTING.md
# This is the commit message #3:

Create ROADMAP.md
# This is the commit message #4:

Update README.md
# This is the commit message #5:

Create README.md
# This is the commit message #6:

Update README.md
# This is the commit message #7:

Update README.md
# This is the commit message #8:

Create OSCAL-PRODUCERS.md
# This is the commit message #9:

Create OSCAL-CONSUMERS.md
# This is the commit message #10:

Update and rename OSCAL-CONSUMERS.md to USERS.md
# This is the commit message #11:

Update and rename OSCAL-PRODUCERS.md to IMPLEMENTERS.md
# This is the commit message #12:

Rename CONTRIBUTING.md to CONTRIBUTORS.md
# This is the commit message #13:

Update README.md
# This is the commit message #14:

Update README.md
# This is the commit message #15:

Update USERS.md
# This is the commit message #16:

Update README.md
# This is the commit message #17:

Update IMPLEMENTERS.md
# This is the commit message #18:

Update README.md
# This is the commit message #19:

Update ROADMAP.md
# This is the commit message #20:

Update USERS.md
# This is the commit message #21:

Update CONTRIBUTORS.md
# This is the commit message #22:

Update README.md
# This is the commit message #23:

Update README.md
# This is the commit message #24:

Update IMPLEMENTERS.md
# This is the commit message #25:

Update IMPLEMENTERS.md
# This is the commit message #26:

Rename CONTRIBUTORS.md to CONTRIBUTING.md
# This is the commit message #27:

Create control.md
# This is the commit message #28:

Update control.md
# This is the commit message #29:

Update control.md
# This is the commit message #30:

Update control.md
# This is the commit message #31:

Update control.md
# This is the commit message #32:

Add files via upload
# This is the commit message #33:

Update control.md
# This is the commit message #34:

Create temp.md
# This is the commit message #35:

Delete NIST-SP-800-53-Rev4-AC1.png
# This is the commit message #36:

Add files via upload
# This is the commit message #37:

Delete temp.md
# This is the commit message #38:

Add files via upload
# This is the commit message #39:

Update control.md
# This is the commit message #40:

Add files via upload
# This is the commit message #41:

Add files via upload
# This is the commit message #42:

Update control.md
# This is the commit message #43:

Update CONTRIBUTING.md
# This is the commit message #44:

Update CONTRIBUTING.md
# This is the commit message #45:

Update USERS.md
# This is the commit message #46:

Update CONTRIBUTING.md
# This is the commit message #47:

Delete CONTRIBUTING.md
# This is the commit message #48:

Delete USERS.md
# This is the commit message #49:

Add files via upload
# This is the commit message #50:

Delete CSA-CCM-IAM02.png
# This is the commit message #51:

Update control.md
# This is the commit message #52:

Update control.md
# This is the commit message #53:

Update control.md
# This is the commit message #54:

Update control.md
# This is the commit message #55:

Update control.md
# This is the commit message #56:

Update control.md
# This is the commit message #57:

Update control.md
# This is the commit message #58:

Update control.md
# This is the commit message #59:

Update control.md
# This is the commit message #60:

Update control.md
# This is the commit message #61:

Delete NIST-SP-800-53-AC1-in-OSCAL-XML.png
# This is the commit message #62:

Update README.md
# This is the commit message #63:

Update control.md
# This is the commit message #64:

Update control.md
# This is the commit message #65:

Add files via upload
# This is the commit message #66:

Delete ISO-27001-Control-A9.png
# This is the commit message #67:

Update control.md
# This is the commit message #68:

Add files via upload
# This is the commit message #69:

Add files via upload
# This is the commit message #70:

Delete ISO-27002-Control-9.1.1-part1.png
# This is the commit message #71:

Delete ISO-27002-Control-9.1.1-part2.png
# This is the commit message #72:

Update control.md
# This is the commit message #73:

Update control.md
# This is the commit message #74:

Update control.md
# This is the commit message #75:

Update control.md
# This is the commit message #76:

Update control.md
# This is the commit message #77:

Update README.md
# This is the commit message #78:

Update IMPLEMENTERS.md
# This is the commit message #79:

Add files via upload
# This is the commit message #80:

Delete oscal-layers.png
# This is the commit message #81:

Add files via upload
# This is the commit message #82:

Delete oscal-layers.png
# This is the commit message #83:

Add files via upload
# This is the commit message #84:

Update IMPLEMENTERS.md
# This is the commit message #85:

Update control.md
# This is the commit message #86:

Update IMPLEMENTERS.md
# This is the commit message #87:

Update control.md
# This is the commit message #88:

Rename IMPLEMENTERS.md to docs/prose/IMPLEMENTERS.md
# This is the commit message #89:

Rename IMPLEMENTERS.md to implementers.md
# This is the commit message #90:

Rearranged and outlined catalog documentation based on the conversation with karen and Wendell.

# This is the commit message #91:

Create catalog-xml.md
# This is the commit message #92:

Rename control.md to catalog.md
# This is the commit message #93:

Update catalog.md
# This is the commit message #94:

Update catalog.md
# This is the commit message #95:

Update catalog.md
# This is the commit message #96:

Update catalog-xml.md
# This is the commit message #97:

Update catalog-xml.md
# This is the commit message #98:

Update catalog-xml.md
# This is the commit message #99:

Update catalog-xml.md
# This is the commit message #100:

Update catalog-xml.md
# This is the commit message #101:

Update catalog-xml.md
# This is the commit message #102:

Update catalog-xml.md
# This is the commit message #103:

Update catalog-xml.md
# This is the commit message #104:

Update catalog-xml.md
# This is the commit message #105:

Update catalog-xml.md
# This is the commit message #106:

Docset migration to Slate

# This is the commit message #107:

Removing unused file.

# This is the commit message #108:

Update README.md

Corrected a typo
# This is the commit message #109:

Add files via upload

Graphical representation of OSCAL schemas aligned with Risk Management Framework steps and tasks.
# This is the commit message #110:

Create CONTRIBUTING.md
# This is the commit message #111:

Create ROADMAP.md
# This is the commit message #2:

Create README.md
# This is the commit message #3:

Update README.md
# This is the commit message #2:

Create OSCAL-PRODUCERS.md
# This is the commit message #3:

Create OSCAL-CONSUMERS.md
# This is the commit message #4:

Update and rename OSCAL-CONSUMERS.md to USERS.md
# This is the commit message #5:

Update and rename OSCAL-PRODUCERS.md to IMPLEMENTERS.md
# This is the commit message #6:

Rename CONTRIBUTING.md to CONTRIBUTORS.md
# This is the commit message #2:

Update USERS.md
# This is the commit message #2:

Update IMPLEMENTERS.md
# This is the commit message #2:

Update ROADMAP.md
# This is the commit message #3:

Update USERS.md
# This is the commit message #4:

Update CONTRIBUTORS.md
# This is the commit message #2:

Update IMPLEMENTERS.md
# This is the commit message #3:

Update IMPLEMENTERS.md
# This is the commit message #4:

Rename CONTRIBUTORS.md to CONTRIBUTING.md
# This is the commit message #5:

Create control.md
# This is the commit message #6:

Update control.md
# This is the commit message #7:

Update control.md
# This is the commit message #8:

Update control.md
# This is the commit message #9:

Update control.md
# This is the commit message #10:

Add files via upload
# This is the commit message #11:

Update control.md
# This is the commit message #12:

Create temp.md
# This is the commit message #13:

Delete NIST-SP-800-53-Rev4-AC1.png
# This is the commit message #14:

Add files via upload
# This is the commit message #15:

Delete temp.md
# This is the commit message #16:

Add files via upload
# This is the commit message #17:

Update control.md
# This is the commit message #18:

Add files via upload
# This is the commit message #19:

Add files via upload
# This is the commit message #20:

Update control.md
# This is the commit message #21:

Update CONTRIBUTING.md
# This is the commit message #22:

Update CONTRIBUTING.md
# This is the commit message #23:

Update USERS.md
# This is the commit message #24:

Update CONTRIBUTING.md
# This is the commit message #25:

Delete CONTRIBUTING.md
# This is the commit message #26:

Delete USERS.md
# This is the commit message #27:

Add files via upload
# This is the commit message #28:

Delete CSA-CCM-IAM02.png
# This is the commit message #29:

Update control.md
# This is the commit message #30:

Update control.md
# This is the commit message #31:

Update control.md
# This is the commit message #32:

Update control.md
# This is the commit message #33:

Update control.md
# This is the commit message #34:

Update control.md
# This is the commit message #35:

Update control.md
# This is the commit message #36:

Update control.md
# This is the commit message #37:

Update control.md
# This is the commit message #38:

Update control.md
# This is the commit message #39:

Delete NIST-SP-800-53-AC1-in-OSCAL-XML.png
# This is the commit message #40:

Update README.md
# This is the commit message #41:

Update control.md
# This is the commit message #42:

Update control.md
# This is the commit message #43:

Add files via upload
# This is the commit message #44:

Delete ISO-27001-Control-A9.png
# This is the commit message #45:

Update control.md
# This is the commit message #46:

Add files via upload
# This is the commit message #47:

Add files via upload
# This is the commit message #48:

Delete ISO-27002-Control-9.1.1-part1.png
# This is the commit message #49:

Delete ISO-27002-Control-9.1.1-part2.png
# This is the commit message #50:

Update control.md
# This is the commit message #51:

Update control.md
# This is the commit message #52:

Update control.md
# This is the commit message #53:

Update control.md
# This is the commit message #54:

Update control.md
# This is the commit message #2:

Update IMPLEMENTERS.md
# This is the commit message #3:

Add files via upload
# This is the commit message #4:

Delete oscal-layers.png
# This is the commit message #5:

Add files via upload
# This is the commit message #6:

Delete oscal-layers.png
# This is the commit message #7:

Add files via upload
# This is the commit message #8:

Update IMPLEMENTERS.md
# This is the commit message #9:

Update control.md
# This is the commit message #10:

Update IMPLEMENTERS.md
# This is the commit message #11:

Update control.md
# This is the commit message #12:

Rename IMPLEMENTERS.md to docs/prose/IMPLEMENTERS.md
# This is the commit message #13:

Rename IMPLEMENTERS.md to implementers.md
# This is the commit message #14:

Rearranged and outlined catalog documentation based on the conversation with karen and Wendell.

# This is the commit message #15:

Create catalog-xml.md
# This is the commit message #16:

Rename control.md to catalog.md
# This is the commit message #17:

Update catalog.md
# This is the commit message #18:

Update catalog.md
# This is the commit message #19:

Update catalog.md
# This is the commit message #20:

Update catalog-xml.md
# This is the commit message #21:

Update catalog-xml.md
# This is the commit message #22:

Update catalog-xml.md
# This is the commit message #23:

Update catalog-xml.md
# This is the commit message #24:

Update catalog-xml.md
# This is the commit message #25:

Update catalog-xml.md
# This is the commit message #26:

Update catalog-xml.md
# This is the commit message #27:

Update catalog-xml.md
# This is the commit message #28:

Update catalog-xml.md
# This is the commit message #29:

Fixed typos, updated repo documentation, and migrated documentation for use in Slate.

Corrected a typo (+4 squashed commit)

Squashed commit:

[6ada57f] Removing unused file.

[503ad71] Docset migration to Slate

[351257e] Update catalog-xml.md

[aae1e8b] Add files via upload

Graphical representation of OSCAL schemas aligned with Risk Management Framework steps and tasks.
@kscarf1
Copy link
Contributor

kscarf1 commented Apr 4, 2018

I have completed all revisions to existing documentation to take this shift in audience into account. All documents are ready for core team review.

@akarmel
Copy link
Contributor Author

akarmel commented Apr 5, 2018

4/5/2018 - Sprint 9 Progress Notes

  • See Karen's note above
  • Documentation is ready for review which will occur on Monday 4/9

@david-waltermire david-waltermire added this to the OSCAL 1.0 M1 milestone Apr 6, 2018
@akarmel
Copy link
Contributor Author

akarmel commented Apr 12, 2018

4/12/2018 - Sprint 9 Acceptance

  • Complete.
  • Closing issue.

@akarmel akarmel closed this as completed Apr 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@anweiss anweiss

@kscarf1 kscarf1

Labels
LoE: Medium User Story
Projects
None yet
Milestone
OSCAL 1.0 Milestone 1
Development

No branches or pull requests
5 participants
@anweiss @david-waltermire @kscarfone @akarmel @kscarf1