Skip to content

SSVC Style Guide

Jump to bottom
Allen D. Householder edited this page Sep 27, 2023 · 1 revision

Style Guide and How-To

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

In the text, please use the following conventions:

  • Names of decision points are capitalized and italics (md is * or _)
  • Values for specific decisions at a decision point are lower case and bold (md is ** or __)
    • Values uppercase at the start of a sentence, but try to avoid such sentence constructions.
  • Headings that declare the decision point name or values should not be additionally emphasized.
    • That is, if the name is the whole heading, don't use emphasis.
    • If the name is part of another heading, use emphasis.
  • Decision points, decision values, and stakeholder decisions should always be in a link cross-referenced to the table in which they are defined.

So we would have: [_Utility_](#utility) or [*Technical Impact*](#technical-impact) which might have values of [super effective](#utility) or [partial](#technical-impact)

  • Names of decisions are italicized (* or _) and lower case.

For example: the decision is to move forward with [*scheduled*](#applier-decisions) priority.

  • This choice collides with decision point names. However, the cap vs lowercase combined with the anchor crossreference is probably enough for readers to distinguish them. Seek feedback on this.

  • Short summaries after the section header declaring the name of the decision point should be in block quotes.

    • For example:
## Exploitation
> Evidence of Active Exploitation of a Vulnerability
  • The short summary should be in title case.
  • There should not be a blank line between the heading and the block quote

How To Use Cross References

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

  • Cross references to other sections can be accomplished with the [text](link) syntax for links.
    • The text to appear goes in []
    • The heading to link to goes in ()
  • Use full heading text, lowercased, with - instead of spaces.

To create an arbitrary anchor

  • use HTML, e.g.:
<a name="anchor-name"></a>

Terms quoted from other sources

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

  • In order not to collide use of emphasis, italics (*word*) should not be used to identify a vocabulary word that is not the name of a decision point.

    • If the word or phrase need not be emphasized, it should simply but put in double quotes (").
    • If the word or phrase needs to be emphasized because it is critical to understanding the passage and it should stand out from the surrounding text, bold can be used (** or __).
    • This style should be used sparingly, primarily for the first place that a key term is defined.

  • Comments in the source code use HTML comments:

<!-- This is a comment that won't show in the output -->
  • Obviously don't put sensitive information in the comments.
  • Comments should be used to note where editorial decisions have been made to about style.
  • For example, though *Exposure* is the decision point, we may still want to talk about exposure generally, and it might be helpful to note in a comment that the word exposure is not emphasized on purpose.

Do not use footnotes.

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

  • There is a markdown style for footnotes (https://pandoc.org/MANUAL.html#footnote)

    • But right now GFM doesn't support that.
    • Footnotes and asides that were not references in v1 have been written in to the flow of the text.

  • If there is some lengthy aside that is helpful, but is too long to be written into the flow of the text, it should be set off with a ---- (horizontal rule) and marked as an aside and ended with another hrule.

  • This style can only be used for asides that are at least a full paragraph.

  • To mark it as an aside, give it a title in block quote format

----
> aside title

aside content
----
  • Don't use Headings (#, ##, etc.) because this will interfere with section numbering.
  • It would be good practice to provide an HTML anchor with the same name as the aside title, so we can cross reference the box elsewhere.

JSON

  • When describing JSON literals in the .md documents, they should be marked up as code literals using backticks (`).

Tables

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

  • GFM uses the pipe_tables markdown extension by default, so tables should use that format.

  • Tables should avoid HTML or LaTeX literal tables, as those aren't portable.

    • If absolutely necessary, include both.

  • Note that when pandoc renders a pipe table into LaTeX if " the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body.

  • Use the table_captions extension

    • In GFM this will render as text, but it will still be helpful.
    • "A caption may optionally be provided with all 4 kinds of tables (as illustrated in the examples below).
    • A caption is a paragraph beginning with the string Table: (or just :), which will be stripped off. It may appear either before or after the table."
    • Put Table: marker above the table, not below it.

Embedding images

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

Use the supported markdown for images where possible and support the link_attributes extension. https://pandoc.org/MANUAL.html#images

![Caption](foo.jpg){width=90%}

This will render as a figure in latex as long as it is on a line all by itself and the implicit_figures extension to pandoc is used. It will render as a normal image in GFM.

Spacing

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

  • Pandoc Markdown will treat a period (.) followed by two spaces ( ) at the end of a line as a request for a line break.

  • Always use only one space after a period, especially at the end of a line.

  • Use unicode characters for opening and closing double quote marks (“ and ”) rather than a straight dumb quote mark (").

  • Do not try to use LaTeX conventions of (``) and ('').

Notes on References

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

The preferred citation method is as follows:

NOTE: These conventions were put in place to make a consistent style for the PDF version of the documentation. Many of them may have been superseded by the move to a website format, but we are keeping them here for now. We expect that we will need to revisit these conventions as we continue to develop the documentation.

  1. Search md_src_files/sources_ssvc.bib for the desired reference
  2. If it's there, use [@referencetag] in the markdown text. For example, the tag in the entry beginning with
    @book{simon1996sciences,

is simon1996sciences 3. If it's not there, add it to the correct subpart of the bibtex file. (books are together, articles are together, CVSS publications are together, etc.) Use authorYYYYword style for the tags (this is the default Google Scholar naming style, which is a good place to get decently formatted bibtex that you can tidy up). Then use the [@referencetag] in the markdown text.

Though the [@tag] command won't reference on github, the html target in the Makefile has the right pandoc commands to create a pretty HTML file with a proper references section.

Clone this wiki locally