Skip to content
KeystoneJS LogoKeystoneJS (α)

Docs Philosophy

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.

1. Tutorials

"Lessons that take the reader by the hand through a series of steps to complete a project."

Tutorials are learning oriented documents.

What matters

  • Learning by doing
  • Getting started
  • Inspiring confidence
  • Repeatability
  • Immediate sense of achievement
  • Concreteness, not abstraction
  • Minimum necessary explanation
  • No distractions

2. Guides

"Guides that take the user through the steps required to solve a common problem."

Guides are problem oriented documents.

What matters

  • A series of steps
  • A focus on the goal
  • Addressing a specific question
  • No unnecessary explanation
  • A little flexibility
  • Practical usability
  • Good naming

3. Reference

"Technical descriptions of the machinery, and how to operate it."

Reference documents are information oriented.

What matters

  • Structure
  • Consistency
  • Description
  • Accuracy

4. Discussion

"Explanations that clarify and illuminate a particular topic."

Discussion documents are understanding oriented.

What matters

  • Giving context
  • Explaining why
  • Multiple examples, alternative approaches
  • Making connections
  • No instruction or technical descriptions

Notes

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.

Credit and Further Reading

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.

https://www.youtube.com/watch?v=t4vKPhjcMZg

He has written a comprehensive blog post on the topic, which is well worth the read.

https://www.divio.com/blog/documentation/

Have you found a mistake, something that is missing, or could be improved on this page? Please edit the Markdown file on GitHub and submit a PR with your changes.

Edit Page