Documentation Style Guide

A reference for public adaptor documentation. Following these rules ensures consistency across the docsite and a better experience for everyone.

Capitalisation

• capitalisation of types: primitives MUST be lower case (string, boolean, number, function), any complex type should be uppercase, like in Typescript (Array, Operation, RequestOptions, State). Object is a funny one but I suggest a plain object should be lowercase.
• Any non-standard type like Options or Response SHOULD have a corresponding @typedef declaration

Spelling & Grammar

• All documentation should be written in American English.
• Sentences should generally end with a full stop

Types

• If a property or parameter support multiple types (including object or array of objects), how should they be styled? Using formal JS doc notation that no-one can understand? Using natural language? Typescript?
• An object with multiple properties should use a typedef rather than adding options.thingy lines to the jsdoc

Examples

• Examples should each have a caption
• Each example should be concise and tell a single story. "Upload some data" or "parse multiple records". Any syntax/options which do not directly support the story should be removed
• Examples should be reasonably realistic
• Examples should generally return data from state rather than define it inline

Changesets and release notes

• Changesets are targeted at users of the adaptor, not other developers
• Focus on API and behavioral changes, not internal/implementation details
• Should we even both to include changesets for documentation?
• A changeset should be a short, concise and specific mention of a change
• Take care to mention any breaking changes and workarounds or migrations
• You do not need to justify, sell or promote any changes in a changeset. Stick to the facts.