Documentation

If you spot small errors or inconsistencies with documentation in our Developer Docs area, please feel free to open a pull request on the directus/docs repository.

All of the pages in the Developer Docs area are authored in markdown in the content directory. The API reference is authored in YAML files in our open source OpenAPI specification repository.

Content in other areas of the documentation is not authored in GitHub. If you see any issues, please open an issue on the GitHub repository.

If you want to contribute tutorials, create new documentation, or suggest non-trivial changes, please first open an issue on GitHub and wait for response from the core team - we are selective about what makes it into the docs for consistency and due to maintenance requirements.

Authoring Guidelines

We care about writing succinct, inclusive, and well-considered documentation. To do this, we follow these authoring guidelines to remain consistent in the rules we apply to our writing.

Structure

Titles

For tutorials, we use the imperative mood instead of the gerund form. For example - "Build an Extension to Show Cat Pictures" instead of "Building an Extension to show cat pictures."

We end each title with technologies and product used, lowercasing the word 'with' before the tools. For example "Send SMS Messages with Twilio and Directus Automate."

Contextualizing and Setting Goals

At the start of each document, contextualize its contents and what the reader will learn. This might require briefly explaining additional concepts around a use case or need.

After this, create a subheading called "Before You Start" and list any prerequisite skills, tools, or permissions that are required for the guide.

Summary

At the end of the post, add a summary that reenforces what the reader has learned and suggest next steps.

Principles

We always follow the following principles:

1. Maintain a neutral, authoritative tone - Use a second-person perspective (you, yours) to directly engage the reader. Ensure that the language is clear, direct, and professional to instill confidence without unnecessary embellishments or personal voice.
2. Be explicit - explicitly state whether a user is in a code editor, terminal, or browser, and when moving between them. Be clear about where lines of code should be added.
3. Be inclusive - words like "simple", "straightforward", or "just" are not a universal truth so avoid them. Use gender-neutral terms when referring to a user.
4. Be concise - always consider how to make sentences shorter and clearer. Also only focus on the parts that matter to your project - remove unnecessary steps like styling, robust error handling, or polish, unless relevant to your topic.
5. Deliver concepts in order - make sure each concept is explained before being referenced. Avoid 'coming back to this later.'
6. Orient the reader - always be clear about which application, page, or where in a page an instruction should take place. Do this before giving an instruction to ensure a reader knows they are in the right place.
7. The what and why - our job to help developers become better developers. As well as explain what to do in a given instruction, why you're doing it, and why it works.
8. Write readable code - use clear variable names, focus on readability and clarity over syntactic sugar or optimizations.
9. Structure documents correctly - make sure headings are
10. Avoid Images - images in documentation are hard to update and quickly fall out of date. Only use if required and follow our image standards below.

Style Guide

• Use title casing for all headings.
• Use Oxford commas.
• Do not capitalize words unless they are part of a product name and presented in full - like "Directus", "Twilio", "Directus Insights". "insights" or "flows" would remain lowercase, for example.
• Use bold formatting only for visible UI elements that need to be interacted with.
• Use inline code formatting when referencing any code (variable and function names) and file names if on the file system.
• Use block code formatting for code that should be typed or copied, or any terminal commands.

Terminology

• Use 'source code' instead of 'codebase'.
• Use 'directory' instead of 'folder' when referring to the file system. 'Folder' is the correct term when talking about the Data Studio or Directus Files.
• When referring to a single Directus instance, we use the word 'project'.
• Use https://directus.example.com as an example URL when calling a Directus URL or initializing an SDK.

Image Standards

Images are important to illustrate concepts, but they can be difficult to keep consistent and maintain.

To prepare Directus for screenshots, please do the following to your project:

• Ensure Directus is using the default light theme with the default purple project color.
• Hide the version number and the beta tag next to Marketplace by adding the following custom CSS: a.v-list-item.link.version, module-nav-content span.v-chip.x-small.outlined.label.chip { display: none; }
• Do not have a user avatar for the current user. Make sure the user's name is 'Admin User'.
• When taking screenshots, ensure there is no browser UI unless this is specifically important for the context.
• Open your Chrome DevTools, open the device toolbar (emulation).
• Select Responsive from the toolbar.
• Set the dimensions to 1920x1080.
• Set zoom to 100% when using Directus, or the most relevant zoom level otherwise.
• While the DevTools are in focus, open the Run Command pane (default ⌘⇧P) and choose 'Capture screenshot'.
• A screenshot will now be in your downloads folder.
• Avoid moving graphics.

Components

Whether authored in Markdown or via our publishing backend, you have access to a number of components.