8000 As a developer, it is not clear how to find docs about developing an app for a Directus instance. · Issue #265 · directus/docs · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

As a developer, it is not clear how to find docs about developing an app for a Directus instance. #265

New issue

Have a question about this project? Sign up for a free GitHub account to open 8000 an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
Akryum opened this issue Mar 25, 2025 · 1 comment
Open

As a developer, it is not clear how to find docs about developing an app for a Directus instance. #265

Akryum opened this issue Mar 25, 2025 · 1 comment

Comments

@Akryum
Copy link
Akryum commented Mar 25, 2025 •
edited
Loading

Let's say I am a developer and my task is to build an app based on a Directus instance using the API or any of the available SDK.

In the current navigation structure of the documentation, it is not clear where to find that kind of information (it's actually under the "Connect" name in the "Guide"). There are also some links towards this information when scrolling down on the home page or in the 4th page of the "Start" tutorial.

As I'm not really interested in the 'User Guide' for studio, I'm struggling to find where to look especially if I unintentionally missed those links which is easy due to the amount of information presented in those pages.

Here are some example questions I might need answer to when opening the docs:

  • What are my options to build an app with a working Directus project?
  • On which URL I need to do a REST request?
  • How to use GraphQL to query Directus?
  • Are there SDKs I can use to make it easier to build an app?
  • What if I'm writing an app using Go, is there a Go SDK (might be community-created)?

Some issues I have found in regards to this in the current docs.

Issues with the Homepage

  1. Home page -> Features -> Data Engine -> Connect

Image

We have two product names here ('Data Engine' and 'Connect') that hide the intent of finding the developer docs.

  1. A bit below in the Home Page, there is 'Directus APIs' section:

Image

  • The Section is titled "API" so if we are looking for SDKs or CLIs we could (mistakenly) skip this section when scanning the page
  • The Quickstart link is labeled "Learn how to connect with Directus", which is unclear if it's doing HTTP requests, connect integrations or setup user authentication.
  • The API Reference link is labeled "Learn how to use the Directus API" but it leads to a section of the docs that actually does not include information about how to use the API to build an app.
  • The SDK link is actually pretty clear and links to the page that has information about the SDKs 👍

  1. Then further down we have links to the Tutorials pages which are pretty dense grids which are a bit hard to scan and I might have to dig to find the information I'm looking for.

  2. The community-created SDKs are not actually listed anywhere else other than on the home page in the section below the Tutorials.

Issues with the Navigation

  1. Start

Image

If I understand correctly this is the Getting started tutorial. I may not click on this one because I'm not actually looking for starting a Directus instance nor am I creating a new project.

After clicking on it though we can see that the 4th page is about using the API 💯 But then on this page there are no links to the "Connect" docs (except the 'See all available query parameters' one), including the SDKs if I'm not interested in doing HTTP requests by hand (or if I want to use GraphQL).

  1. The Guides menu doesn't have any items that are related to developers or building apps with the Directus APIs/SDKs.

Image

But in fact there is one, it's the 'Connect' item which is something I don't really know what it is for unless I click on it.

  1. Resources does link to the Tutorial pages I mentioned above with the drawbacks they have.

  2. API Reference links to a page that has very little documentation about how to do a REST or a GraphQL query to the Directus instance, but it does have a link to the SDKs page in "Connect".

Some proposals

  • Having a dedicated section for developers with:
    • How to use the API (Rest and GraphQL)
    • How to Authenticate (using the API)
    • Official SDKs
    • Community SDKs
    • How to use the CLI
    • Docker images maybe?
    • How to create extensions
    • ...
  • Promoting the Developer-related docs in the navigation header
  • Rename "Connect" to something clearer like "APIs & SDKs" or "Developer Tools"
  • List the community-created SDKs in the SDK page
@linear Linear
Copy link
linear bot commented Mar 25, 2025

DX-869 As a developer, it is not clear how to find docs about developing an app for a Directus instance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@Akryum
0