README
Last updated
Last updated
Mycroft Documentation
Head to https://mycroft.ai/documentation for all public facing documentation. The website is automatically updated from this repo.
The purpose of this repo is to unify all the documentation for the public-facing components of Mycroft.AI, and to reduce the fragmentation of documentation.
It is intended that the Markdown in this repo will be consumed by transformation layers or integrations to present the documentation in a user-friendly way.
@krisgesling - Kris Gesling kris.gesling@mycroft.ai
At the time of writing, the Docs Repository has only a single branch, master. This is the default branch for the repo.
The following conventions are observed in Mycroft documentation:
All code is presented like this
All Mycroft-specific terms are bolded
Information is presented in 'inverted pyramid format'. This means an overview is given first, then more detailed information, then more granular information.
Human-written documentation is done in Markdown, on GitHub
Documentation of code is done through Google DocStrings format https://google.github.io/styleguide/pyguide.html#Comments and this then passed to documentation generators.
Styling conventions
The following conventions are used for styling technical terms and related phrases.
internet is always written in lowercase, never as Internet unless at the start of a sentence.
Mark 1 is always styled as such
Metadata is always styled as one word
Micro SD card is always styled as such, not as micro sd card, micro SD card or alternatives
Picroft is always styled as such
PocketSphinx is always styled as such
Skill Author is always used to refer to the developer, writer or creator of a Skill.
Speak is always capitalized given the importance of Speaking in a voice interface.
User is always capitalized as a sign of respect for our Users.
How voice interactions are presented in documentation
To make documentation easier to read, voice interactions should be presented in a consistent style.
How to present a User Speaking
When a User Speaks, it is always presented in the style of a quote:
Hey Mycroft, what time is it?
When Mycroft Speaks, it is always presented in quote marks in preformatted style:
"The time is 12.30"
Mycroft documentation is written with the following tone of voice:
Knowledgeable but never arrogant
Helpful but encouraging of self-discovery
Easily readable, but not dumbed down
Use this handy checklist when creating or modifying documentation:
See the Contributing Guide for Mycroft Documentation
