Authoring guidelines

These are the guidelines for writing documentation for Arcade, to help keep the tone and style consistent across the docs.

Writing style

Clarity and simplicity: Write in short, concise sentences. Focus on simple language and avoid unnecessary jargon. The topic is complex enough; keep the language simple wherever possible!
Action-oriented: Use verbs that guide the reader through tasks step by step, such as "Install," "Run," "Initialize," or "Authorize."
Sentence case: Use sentence case for titles and headings.

Active voice: Write in an active voice to make the instructions direct and easy to follow. Example: “Install Arcade” rather than “Arcade should be installed.”
Friendly and supportive: Assume the reader is unfamiliar with Arcade but is eager to learn. Keep the tone positive, friendly, and approachable.
Developer-focused: Tailor your language to a developer audience, using code-centric explanations but ensuring clarity for beginners. Assume the reader knows Python but might be unfamiliar with Arcade’s specifics.
Encouraging exploration: Use phrases that invite readers to try things out and explore the capabilities of Arcade. Example: “Let’s try…” or “You can explore…”

Code first: Provide code snippets upfront and supplement them with explanations afterward. Code should be clear and easy to copy/paste without unnecessary formatting.
Contextual comments: Use comments in the code snippets to explain key parts, but keep them brief. Only highlight what’s essential for the user to know in that specific step.
Appropriate indentation: Use 4 spaces for indentation in Python code. Use 2 spaces for indentation in other languages.

Arcade: Always refer to the product as "Arcade" in both titles and body text. Do not abbreviate or shorten the product name. Do not append "AI" to the product name.
Engine: Refer to "the Arcade Engine" when the deployment option is irrelevant. Otherwise, refer to "the Arcade Cloud Engine" or "a self-hosted Arcade Engine."
Toolkits: Toolkits are collections of tools, either built by Arcade or a third party developer. For toolkits built by Arcade, refer to "the Arcade [Toolkit name] toolkit." For example, "the Arcade GitHub toolkit."