Home

SSVC Project Documentation

This wiki contains documentation for SSVC project contributors.

See also CONTRIBUTING.md in the main repository.

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.)

Diátaxis Framework

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.