Keystone is a complex project with a large surface area and as such having good documentation is important for both developers and users. This document outlines the philosophy behind how the Keystone documentation is organised, so that you can contribute docs easily and effectively.
Our documentation is grouped into four main categories, each of which has a specific purpose and context.
"Lessons that take the reader by the hand through a series of steps to complete a project."
Tutorials are learning oriented documents.
- Learning by doing
- Getting started
- Inspiring confidence
- Immediate sense of achievement
- Concreteness, not abstraction
- Minimum necessary explanation
- No distractions
"Guides that take the user through the steps required to solve a common problem."
Guides are problem oriented documents.
- A series of steps
- A focus on the goal
- Addressing a specific question
- No unnecessary explanation
- A little flexibility
- Practical usability
- Good naming
"Technical descriptions of the machinery, and how to operate it."
Reference documents are information oriented.
"Explanations that clarify and illuminate a particular topic."
Discussion documents are understanding oriented.
- Giving context
- Explaining why
- Multiple examples, alternative approaches
- Making connections
- No instruction or technical descriptions
Keystone 5 is still in the alpha phase of development, and the documentation is still evolving. PRs which contribute new content, or which improve the existing content by editing it to better suit its category are welcomed.
This model of documentation is borrowed directly from a talk given by Daniele Procida at Pycon Australia 2017, and all credit for these ideas belong to him.
He has written a comprehensive blog post on the topic, which is well worth the read.