Writing Docs
The following is a set of style guidelines we would like all contributors to adhere to.
For simplicity's sake we try our best to adhere to Google's developer documentation style guidelines. They are merely guidelines and not strict rules. Feel free to break free from the guidelines when it makes sense. (Even Google suggests this themselves.)
Below we have included any important notes in regards to creating our documentation. You are welcome to ask for advice in our Discord if you are unclear about anything.
Images:
Images must use unique file names, or they will break conflicting images upon upload. (This is a quirk with gitbooks.)
Use image compression if possible to reduce the filesize of images,
Text Formatting:
Base style guide
We loosely follow the Google Developer documentation styling guidelines,
🚧 copy paste the key bullet points
🚧 add link to their guide
Enhance pages with LLM.
if possible, use this prompt: 🚧
Page description guidelines:
gitbook allow to enter a short pure-text (no bold, ...) page description on each page.
If possible, add one, but keep it very short.
be descriptive about what this page is about.
Naming: prefer one word
❌ Cushy SDK, Cushy Apps, Cushy Studio
🟢 CushySDK, CushyApps, CushyStudio
Page intros
every page should start with a few oneliners paragraphs about
one sentence to define stuff
one sentence per other page that is closely related
great way to block things
Nesting
level0 top level group index-pages
should never have unique content. only summary.
Should have one link to every sub page + at most one or two paragraph (possibly 0)
level1 page should have one single main topic
if a feature have 3 main subfeatures, we add 4 pages. all at the same level, because users will look for any of the 3 main subfeatures as much as the main feature. that also help
2 options
Only the main feature have the big documentaion, and other pages have one paragrah, one picture, and then point to main page
Last updated