Your documentation is really bad

[Chasen-Zhang]

https://docusaurus.io/ is recommended.

[Reinmar]

Thank you.

What would be the 3 most important things to fix?

[MatthieuScarset]

+1 to improve the documentation.

1. Fold all pages + highlight somehow the page currently being read in the sidebar navigation on the left.

As you can see on this page for instance, I'm reading the "Create a simple plugin" page but I can't find it anywhere in the left sidebar. I have no idea where I am in the doc's content. I can't find my way to other parent/sibling pages.

After seconds of squinting my eyes, I finally find the page with the light grey background. But all the other sections are open. I lost my train of thoughts with such a lot of texts to read so, I'm lost again.

2. Simplify plugin examples and provide graphic

We need more graphics to understand how plugin works. A picture worth a thousands words... I don't want to read the full page. There's too much text and most parts are repeated on other pages (such as Your index.html should look as listed below... and the JS / HTML code).

3. Provide example of writing VanillaJS

I understand it is intended to work with modern JavaScript framework, installing dependencies, building and watching over and over again. But there are many developers out there who want to extend CKEditor without having to learn entire frameworks or even less, the CKE5 API. For instance, I maintain a few Drupal modules and I need to provide CKE5 integration but I dislike working with CKE5.

I need - and many other will - easier entry points to extend CKE5.

At least one example of a plugin written in plain VanillaJS.

[MatthieuScarset]

I forgot to mention that the page explaining the error code is not helpful.

For instance, I had this error: CKEditorError: plugincollection-plugin-not-found {"plugin":null}, and your doc says:

I can tell a plugin is not found myself by simply reading the error message :-1: :facepalm:

Please provide suggestions to debug situations.

[Witoso]

@MatthieuScarset thanks for the suggestions (cc @apadol-cksource).

We need more graphics to understand how plugin works.

Do you have some examples that we could use for inspiration? Maybe Drupal has something that we could take a look at?

1. Provide example of writing VanillaJS (...) I need - and many other will - easier entry points to extend CKE5.

Noted, we will soon publish some docs that will make it a bit better. As for vanilla JS, we have some hard stops in the framework. Making the UI/widgets work as CKE4 (no building), requires significant time and development on our side but we are discussing this internally.

[MatthieuScarset]

We need more graphics to understand how plugin works. Do you have some examples that we could use for inspiration? Maybe Drupal has something that we could take a look at?

Usually I like to have graphics to explains data flow. In the context of CKE5, we need a graphic to explain the upcast, downcast, editingDowncast... and any other mysterious casting things happening.

Here's two examples from Gutenberg editor:

• https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/#serialization-and-parsing
• https://developer.wordpress.org/block-editor/explanations/architecture/modularity/#editor-packages

---

Addition to the original list of improvements required for the documentation to be actually helpful:

We need an example of How to apply a span on a selected text

[MatthieuScarset]

Cross posting https://github.com/ckeditor/ckeditor5/issues/14782

[Witoso]

Usually I like to have graphics to explains data flow. In the context of CKE5, we need a graphic to explain the upcast, downcast, editingDowncast... and any other mysterious casting things happening.

The best example would be on the page about the editing engine (although for me, it's too confusing as well, we need to think how to change this).

For instance, I had this error: CKEditorError: plugincollection-plugin-not-found {"plugin":null}, and your doc says:

As I haven't answered this one, this is the first time I see null, and most likely there's some bump on the Drupal \<> CKEditor layer. As you can imagine, when there's a plugin name, the error becomes self-explanatory.

[Chasen-Zhang]

Thank you.

What would be the 3 most important things to fix?

1. I expect more examples, can directly run through the example, every method or every function has an example, and the example must be complete, this is to let the beginners quickly get started
2. Could you please add some explanation of the overall architecture diagram
3. I personally feel that the document needs to be sorted out, too messy, I don't know where to start.

By the way, Ckeditor is a very good product and I don't want users to be intimidated by the documentation❤️

[Witoso]

@Chasen-Zhang thanks for details. We have different developer types that use the documentation:

1. Integrators: people that want to integrate the editor in their app, with two main approaches:
   1. Out-of-the-box: using the default setups.
   2. Customization: customizing the editor with different plugins.
2. Editor developers: devs building new features on top of the editor's framework.

Those are not exclusive, and I am curious as to which group you would have assigned yourself to.

[reeveng]

Some things that come to mind:

1. how translations work for external plugins
2. upcast and downcast => when creating custom plugins, it is not clearly explained
3. more examples in general when it comes to creating custom plugins would be very helpful, not sure if we can look at existing ck5 packages (internal plugins)
4. how to use the debug tool / what we can debug with it, besides a side note here and there, as far as I know the documentation is extremely limited on what it should/could be used for
5. can also agree with @MatthieuScarset , that often the pages and structure of everything is very confusing in the docs, I nearly always have to search for something and use the search function, the sidebar is basically useless to me (even when I just want an underlying article)

[Chasen-Zhang]

@Chasen-Zhang thanks for details. We have different developer types that use the documentation:

1. Integrators: people that want to integrate the editor in their app, with two main approaches:

   1. Out-of-the-box: using the default setups.
   2. Customization: customizing the editor with different plugins.
2. Editor developers: devs building new features on top of the editor's framework.

Those are not exclusive, and I am curious as to which group you would have assigned yourself to.

I'm a Integrators ❤️

[auliarahmed]

Thank you. What would be the 3 most important things to fix?

1. I expect more examples, can directly run through the example, every method or every function has an example, and the example must be complete, this is to let the beginners quickly get started
2. Could you please add some explanation of the overall architecture diagram
3. I personally feel that the document needs to be sorted out, too messy, I don't know where to start.

By the way, Ckeditor is a very good product and I don't want users to be intimidated by the documentation❤️

number 3 is 100% true! i hope the docs simple for new user like me, maybe in the next version (6) ckeditor have better docs