As a user, I should be able to easily edit my narrative text in the component.yaml

[jcscottiii]

Right now, the narrative section has to contain formatting in order to represent sections.

Old

Example.

  narrative: "#### b  \nAudit logs will be made available to organizations for mutual\
    \ support in response to security breaches, system and user access, incident reporting\
    \ and continuous monitoring.\n18F will generate and distribute audit reports,\
    \ provide customized dashoard access for audited events, and send audit log data\
    \ to SIEM and log analysis systems from its  audit logging and metrics tools for\
    \ the Cloud.Gov platform and virtual infrastructure as needed.\n  \n#### c  \n\
    18F retains audit logs according to NARA retention standards to provide support\
    \ for after-the-fact investigations of security incidents and to meet regulatory\
    \ and organizational information retention requirements.\nThe log management framework\
    \ will provide the capability to retain logs for 90 days online and one-year offline,\
    \ with sufficient capacity as to mitigate the risk of exceeding storage space.\n\
    Specific Policies, Procedures, Points of Contact, and Guidance will be established\
    \ between 18F and other agencies to support after-the-fact investigations, by\
    \ the 18F Project Lead.\n  \n"

After talking with @dlapiduz and @clovett3, something like this would be better

  narrative:
    - key: b
      text: "Audit Logs ......."
    - key: c
      text: "18F retains ..."

Then each template filler (markdown or docx) can determine how to format each section. In addition, a user could easily paste in the text.

[afeld]

For starters, YAML has a better way of handling multi-line strings:

narrative: |
  #### b

  Audit logs will be made available to organizations for mutual support in response to security breaches, system and user access, incident reporting and continuous monitoring.

  18F will generate and distribute audit reports, provide customized dashoard access for audited events, and send audit log data to SIEM and log analysis systems from its  audit logging and metrics tools for the Cloud.Gov platform and virtual infrastructure as needed.

  #### c

  18F retains audit logs according to NARA retention standards to provide support for after-the-fact investigations of security incidents and to meet regulatory and organizational information retention requirements.

  The log management framework will provide the capability to retain logs for 90 days online and one-year offline, with sufficient capacity as to mitigate the risk of exceeding storage space.

  Specific Policies, Procedures, Points of Contact, and Guidance will be established between 18F and other agencies to support after-the-fact investigations, by the 18F Project Lead.

http://stackoverflow.com/a/21699210/358804

[dlapiduz]

@afeld I think we want to be able to break it down by sections so you have a way to stack it with other docs.

Like:

uaa.yaml:

 narrative:
    - key: b
      text: "Audit Logs ......."
    - key: c
      text: "18F retains ..."

cf.yml:

 narrative:
    - key: b
      text: "More logs"

[dlapiduz]

@jcscottiii I think you said there was a change to make this work? Or was it just the multi line string?

[afeld]

Re-posting my question from https://github.com/opencontrol/compliance-masonry/pull/143#issuecomment-221978229: is the 'narrative' always going to have those sections beneath it, or should we also handle its value being a single string?

[afeld]

Closed by https://github.com/opencontrol/compliance-masonry/pull/160.

[pburkholder]

https://github.com/18F/epa-notice/pull/425 was an instance of user writing:

- standard_key: NIST-800-53
    control_key: AC-2   # Account Management
    narrative:
     text: >

when you need:

- standard_key: NIST-800-53
    control_key: AC-2   # Account Management
    narrative:
 -    text: >

I've hit the same issue myself. I think we need to revisit @afeld's suggestion from https://github.com/18F/compliance-toolkit/issues/25#issuecomment-222309659 or even revert this change, as the chance for user error is higher than just doing following https://github.com/18F/compliance-toolkit/issues/25#issuecomment-221364171 with

narrative: |
  #### b

  Audit logs will be mad...

  #### c

  18F retains audit logs according to NARA...

[afeld]

Still an open question of whether we want to officially support Markdown in the narrative section: https://github.com/opencontrol/schemas/issues/13

At the very least, we should give useful errors if the data isn't structured properly: https://github.com/opencontrol/compliance-masonry/issues/135