-
Notifications
You must be signed in to change notification settings - Fork 34
Home
This wiki contains documentation for SSVC project contributors.
See also CONTRIBUTING.md in the main repository.
/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.
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.)
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 |
-
/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.)
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.
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.