Style Guide for OSCAL Documentation

[aj-stein-nist]

User Story:

As a NIST OSCAL developer, in order to understand how to write documentation in this project for proper style and to understand what words are jargon and/or official terminology, I would like the NIST OSCAL Team to provide a style guide I can reference while I draft documentation and cite when reviewing documentation updates to clarify intent and expectations.

Goals:

Many times during pull requests for code review that involves documentation, we discuss language style and particular what terms are specifically official OSCAL jargon (capitalized) and what are informal or common terms in software development and/or information security, so they are lowercase.

Example: https://github.com/usnistgov/OSCAL/pull/1167#discussion_r827449108

It was asked in the weekly status update to create an issue with a style guide to discuss, covering this and more substantive documentation issues.

Dependencies:

{Describe any previous issues or related work that must be completed to start or complete this issue.}

Acceptance Criteria

• [ ] All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• [ ] A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• [ ] The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[wendellpiez]

Top-level outline?

• Goals, scope and audience / users
• Technical terminology
  • Usage ("prefer common nouns" etc.)
  • Inline style - italics, capitalization etc. - and data sources
  • OSCAL terminology
    • OSCAL objects / formal names
    • OSCAL concepts
• Citations and links
• "Simple" English (with links) https://www.plainlanguage.gov/
• NIST style guides (with links)

Please comment to add anything including minor small things that should not be missed.

Noting that for this to be effective, people will have to be able to use it, and that requires that it be brief, direct and easy to follow.

[aj-stein-nist]

Sweet, thanks so much @wendellpiez! You actually hit a lot of themes and requirements I wanted, especially plainlanguage.gov! I think this is great, I will think about anything we could/should add and refine it.

[wendellpiez]

We could do worse than call out to https://developers.google.com/style among other external resources.

[galtm]

@wendellpiez , your work in progress looks awesome. I'm impressed by how quickly you pulled this together.

[aj-stein-nist]

Be sure to incorporate how to format terms in OSCAL (and Metaschema of course given the context of why I am noting this) when those terms are our own terminology and happen to syntax keywords, re my comment in metaschema#275 review.

[wendellpiez]

:+1: might be something there already. Incidentally there is also going to be a CSD Style Guide or so I hear.