Documentation

[Syed-Sheharyar]

Summary

https://getsnapfont.com/posts/directus-one-year-later-what-i-learnt

I didn't write this post someone on the Reddit shared I also face same kind of problem which motivates me to discuss here.

Reddit Post link - https://www.reddit.com/r/webdev/comments/17qhwss/what_i_learnt_after_using_directus_cms_for_over/

Basic Example

Start some hackathon or any event using this discussion as a base specifically for improving docs. Improving means any kind of small feature, API method should have atleast 10 examples to do the same thing in different angles and different implementations.

Motivation

Such a huge project and users not satisfied with docs is not acceptable. The true motivation of this discussion is to start some kind of event where community send their own version of docs core team also write their own and decide later which is better. For example, write some documentation on some of the most useful M2A relations. Directus Blog is good resource but there are many things that should be discussed in a practical way or should go in deep in documentaion. Docs are too important if you want that users take full advantage of your product or use at it's fullest capabilities.

Detailed Design

Full revamped of Directus docs site like how how you revamped the UI and design of directus.io recently.

It should be some kind of event where people can share their thoughts on current state of documentation and decide the future. Documentation should be written in a way that even a beginner who just started programing a month ago can understand what docs are saying about or refering to.

It can be some kind of flow that take first time lander on your docs site from the start to finish. Started from Directus basics to go more deep and deep. With examples and tones of different kind accepted by the community. Create videos on Your Youtube channel which give some users to go deep with video not everybody likes to go through a huge written document.

Requirements List

Must Have:

• A New UI for Directus Docs necessary for attracting new people
• B Every feauture, API even an internal variable or function which might help people or improve something should be discussed thoroughly

Should Have:

• C New issues with tag "Docs Revamp" to track current status

Could Have:

• D A community section in Docs which might not ended up in Final Docs here users write about some specific thing or how to do that or how not to. Might be user share their code examples here as well to do something specific

Drawbacks

This little improvement or cummunity effort becomes a real problem for Directus competitors.

Hence this drawback is for Directus competitors and not for Directus itself. Great

Alternatives

Alternatives can be discussed in comments. The only thing we should ensure from this discussion that no part of any feature or function remains undocumented. Ensure that nobody in the future have same remarks for Docs as this article.

One alternative is instead of discussing practical examples of features in Directus blog add a new examples section as well. Which can have real world 4 to 5 examples and how to use that feature combined with others.

Adoption Strategy

It itselfs serve as an adoption for any new user lands on Directus Website or Docs not a breaking change anyway. Just make things simpler to understand and adopt Directus in Docs.

Unresolved Questions

Why there is not any general template for Discussion like this is not a feature request but a huge improvement to Directus ecosystem and community. A general template for Discussion is itself serve as an improvement for more of these dicussions.

[Syed-Sheharyar]

Again, I highly recommend start some kind of event specially for Docs improvement and undiscussed part of your features. It should not take months you can even start this today with motivation for making docs simple to understand. Please give it a clear attention and try to start some kind of event in this month or next because this is the only way to attract the community that you are focusing on Docs Revamp. Which in result increase the adoption rate of Directus. Lastly, I say that Directus is not only a community it's an ecosystem like Wordpress.

[Boegie19]

I don't agree with that everyting needs to be documented stuff like internal functions that are not stable should not be documented.
Still I agree with that the documentation around extensions is almost none existent and the guides exists but are not advertised properly they are at the bottom of the page with noting special about them so I did not even see it until now.

[Syed-Sheharyar]

Yeah, it almost a week now they are not giving attention to this. For internal functions docs I agree with you. The only functions or helper utilities should be documented that stable and helpful for the community or might be some hacky solutions to any problem. I myself following Directus CMS for 6 months and quality of documentation is not too great and there are some stuffs like extension documentation like you mention doesn't exist for the most part. Lack of docs force people to create issues on GitHub for something might be very basic to do but not well written. The current docs site doesn't give you a flow as well like from where to start where to find something. I found some extension docs of directus after one month of using it.

[phazonoverload]

Hello! I run the team that owns documentation among other things. There's a lot to digest here but wanted to provide some insights and thoughts:

Firstly just wanted to respond to the idea that we're not giving attention to an open feature request after a week. Our feature request process does say we don't have the ability to get to requests unless they meet the required upvotes after 90 days. That's a pretty universal thing but don't want you to think we're ignoring this, or you, specifically.

Start some hackathon or any event using this discussion as a base specifically for improving docs.

Writing high quality and consistent documentation is a huge and skilled task, and not one we will organize efforts around for community members to contribute piecemeal. When there are large changes to make, we fully plan a project and have our educators set aside time to make it happen.

Such a huge project and users not satisfied with docs is not acceptable.

100% agree, but you're also seeing a tiny snapshot of feedback. We take all feedback seriously and genuinely to take it in, prioritize it, and plan on improvements where needed, but our general reported docs satisfaction is not bad and a lot better than this time a year ago. 😅

It can be some kind of flow that take first time lander on your docs site from the start to finish.

I'm glad you said this because... yes! We agree. In fact this set of 'learning paths' is something we will be building out in the new year. There is a lot of good information but it needs organizing in a linear path for those just starting.

A New UI for Directus Docs necessary for attracting new people

Is it? And interesting this is the first item you put in 'must haves'.

Every feature, API even an internal variable or function...

I've mentioned this elsewhere, but we document what people should rely on. Directus has a load of internal logic that can be used, but shouldn't. They are more volatile than things we do document. This is something where people will always be unhappy - document it and it changes, or don't document it and folks realise it exists - can't please everyone!

For what it's worth, there's an open PR right now which documents many of the internal services which are important for building extensions. Once again, slightly volatile, but once we saw enough people were using them and asking questions, we realised we can help both them and us by documenting them.

A community section in Docs which might not ended up in Final Docs here users write about some specific thing or how to do that or how not to. Might be user share their code examples here as well to do something specific

We have that - it's the Developer Blog. The reason why this exists is to basically act as a playground for new ideas that don't need to be maintained. The expectation from docs is that they are maintained and up to date. Blog posts don't have the same expectation. And that's why I would be hesitant to have a free-for-all on the docs - like the main code powering Directus, a contribution doesn't end at merge. It's then down to us to maintain and that's why the bar is high.

Why there is not any general template for Discussion like this is not a feature request

Because we use Discord for discussions.

---

From your comment

Again, I highly recommend start some kind of event specially for Docs improvement and undiscussed part of your features

Yeah, actually, I love that idea but events aren't always inclusive. We actually track feedback at the bottom of every docs page, in our text conversations on Discord, and any 1:1 chats we have with users and customers. I know it may not seem it, but we listen, take notes, and make improvements almost every day.

---

From @Boegie19's comment:

the guides exists but are not advertised properly

Advertised may not be the right word, but I think they are hidden away for sure. Above I mention learning paths - building extensions is part of that! It's quite likely guides for Directus tools & extensions will end up in their respective sections rather than tucked away in a guides section. Not sure yet - like I said, work on how docs are organized is starting soon.

The broken search also doesn't help. It's basically polluted by the package pages - content hidden away can be more tolerable when search behaves. Literally got a code editor open now working on that. 🙈

---

Overall I agree with you - there's plenty of work to do. But there's also plenty of work that has been done and it's been prioritised based on need. Extensions are the current area of focus, but it's the current item in a long list. A list that forever grows, and is prioritised, and the cycle continues.

If you ever think something is missing, please open an issue here, or use the feedback widget on a docs page. If you want it to be a conversation, kick it off on Discord. We're here, and we listen.

[Syed-Sheharyar]

The reason I'm reporting is to give feedback on the current state of the documentation. However, it seems that most of the improvements are planned for next year.

Writing high-quality and consistent documentation is a huge and skilled task

You need someone who truly dedicates his/her time to improving the docs. In the end, your team writes it first and can further improve through community contributions.

Is it? And interesting this is the first item you put in 'must haves'.

Yeah, because the site is not too pretty while not every user wants great UI/UX though your docs are mostly used by developers or designers. And, they prefer UI/UX. Also, New docs site design means something big and you can also add some kind of learning path or flow. Within 5 days 5 announcements. Directus' main website was completely redesigned which attracted me more than the announcements. It's human nature if you do a big rewrite of docs then a new website will surely going to attract people visually.

Now, I hope that there's some improvement in docs next year as planned and yeah your blog is also a great resource.

[rijkvanzanten]

Heya! Thank you for taking the time to submit this request!

It has been over 90 days, and this discussion has not received at least 15 votes from the community. This means that we don't feel like there's enough community interest to warrant further R&D into this topic at this time. 🧊

This request will now be closed to keep our discussions tidy. Please reach out if you have any questions!

For more information, see our Feature Request Process.