Home

SSVC Project Documentation

This wiki contains documentation for SSVC project contributors.

See also CONTRIBUTING.md in the main repository.

Where to contribute

The repository this wiki accompanies contains

• documentation that forms the basis of the certcc.github.io/SSVC website
• python modules that support implementers of SSVC as well as the production of that documentation
• javascript that provides the SSVC calculator

Translation

Right now we don't have any plans for translations, but if you have interest in that let us know.

Contributing to the documentation

The English text lives in the docs subfolder. We welcome any issues from anyone in the community, so we can discuss them and improve SSVC. If you have a suggestion, please create an issue.

In general, please create an issue before making a pull request to submit a change, except in the case of fixing a small typo, etc. Please check that your suggestion does not overlap with existing issues (including closed ones)

Please see the remainder of this wiki for style guides, etc. to help us keep any suggestions or commits consistently aligned with our style preferences.

Contributing code

The tools for working with SSVC live in the src subfolder.

We have limited tooling at the moment. The expectation is that these will mostly be flexible helper-type scripts and plug-ins. Therefore, interoperability is important. Where the code implements or directly references some aspect of the English document, please make that linkage explicit. We use config files stored in data to prevent code in src from having fragile dependencies on the English doc. We would like to minimize manual change management, but at the very least we need to document where changes in the document need to result in changes to code. Information likely to change based on changes to the English should go in config files to be stored in the data subfolder. Code in the src folder should (as robustly as plausible) be reading that data in.

The process is similar to that for the doc, though the language is different. Please create issues before making pull requests. Pull requests on code should be clear about what they've changed and what you've done. Thanks in advance!

Definitional documents

/docs contains the text documents that describe the decision process, the decision points, the possible decision values, and the decision trees that should be used to reach prioritization decisions.

We use mkdocs to build the documentation website. The mkdocs.yml file in the root of the repository contains the configuration for the website. The docs folder contains the markdown files, css, and other assets that are used to build the website.

We are using 'material for mkdocs' to provide the theme and some extensions for the website.

The documents are in markdown for easy editing.

Local development

To build the documentation locally, you will need to install mkdocs and mkdocs-material:

$ pip install -r requirements.txt

Then you can run the development server:

$ mkdocs serve

And browse to the local web server, which defaults to localhost:8001.

(Use the --dev-addr option to change the port if desired.)

Documentation Organization

We are using the Diátaxis Framework to organize our documentation into four main categories, oriented around the different ways that people might need to learn about and use SSVC.

Contributors should follow the Diátaxis Framework's Map of Needs to determine where to put new content. Summarizing the map:

	Tutorials	How-to guides	Reference	Explanation
what they do	introduce, educate, lead	guide, demonstrate	state, describe, inform	explain, clarify, discuss
answers the question	"Can you teach me to...?"	"How do I...?"	"What is...?"	"Why...?"
oriented to	learning	tasks	information	understanding
purpose	to allow the newcomer to get started	to show how to solve a specific problem	to describe the machinery	to explain
form	a lesson	a series of steps	dry description	discursive explanation
analogy	teaching a child how to cook	a recipe in a cookbook	a reference encyclopedia article	an article on culinary social history

Documentation Directory Structure

• /docs/tutorials - Tutorials
• /docs/howto - How-to guides
• /docs/reference - Reference
• /docs/topics - Explanation
• /docs/about - project-level information (e.g., about, contributing, etc.)
• other directories as needed for the website (/docs/assets, /docs/stylesheets, /docs/javascript, etc.)

Markdown file naming conventions

Previously we had used a more strict naming convention for the markdown files, but we have relaxed that to allow for more flexibility in organizing content in the future.

PDF and HTML output

We are no longer generating PDF or single-HTML-all-in-one-file output for the documentation. This is because the documentation is now organized as a website, and maintaining multiple formats adds a lot of overhead.

We may revisit this decision in the future, but for now we are only generating HTML output in the form of a website.