Complete Docs

[zbeyens]

The docs have been concise and straightforward for easy maintenance. @TomMorane will help to rewrite the docs so it's more prose and complete.

This includes:

Guides:

• Reset editor
• How to create a custom plate component (+ types)
• Keyboard Shortcuts

Core:

• full core API (queries, transforms)

For each plugin:

• prose overview
• prose demo
• API (e.g. createBlockquotePlugin()) queries, transforms
• default values of a plugin: people can go to the source code to see the internals of a plugin but we should expose interesting default values like hotkey, key, default options, etc.
• new section for HTML deserializer support
• basic elements and basic marks: a section for each plugin.
• a section for each plugin toolbar buttons

Plugin Sections:

• (overview)
• Demo
• Installation
• Options (if any)
• Transforms
• Queries

@12joan I'd love your feedback on what you'd like to see as improvement and additions, per page or new pages.

[12joan]

Adding more content to the docs sounds like a great idea! 😃

One of the things I struggle with most when working with Plate is not knowing what helper functions are available for me to import and use. Since every function used by every plugin is exported from Plate, there's a lot of clutter on the API reference, making it hard to spot the really useful functions like findNode and getBlockAbove hidden amongst them. Documenting the most important of these functions prominently, along with real-word examples of when you'd want to use them, would be immensely helpful.

I took a look at the last five pages of Discussions and made a note of which topics were asked about frequently. Here's what I found:

• Accessing the editor object
  • The plate hooks must be used inside the <PlateProvider id={id}> component's context. #1455
  • How can I apply Transforms to programmatically change content in Plate? #2002
  • Access the editor instance inside event handlers #2158
  • How to reset editor from outside of it? #2193
• Serializing and deserializing HTML
  • Need help exporting the content and display editor content as HTML. #1376
  • Current support for HTML serialization #1872
  • Plate initialValue from HTML string #1727
  • How to deserialize html #1792
• Making the editor read-only
  • How can I display the contents while turning off editing mode? #1808
  • How to render JSON output from Rich-text-editor like (plate) in react js #2199
• Plate as a controlled component
  • Plate - dynamically update editor value from props #1262
  • How can we dynamicaly set editor value by props? #1905

Accessing the editor object is quite counter intutive, since nothing in the names of the relevant hooks tells you they can only be used inside PlateProvider. Mentioning this and explaining how to correctly access the editor in the Getting Started section of the docs would probably help every single new user of Plate. (As a side note, maybe we should add an explicit error when these hooks are used incorrectly, linking users to the part of the docs where this is explained.)

It would also be helpful to have guides for common patterns, like running a callback (that has access to the editor) every time the editor changes.

As one user noted, the large number of source files used in each of the current examples makes it hard to figure out what's special about that example in particular. Highlighting this information in the text would help to mitigate this problem. E.g. "In this example, the rules defined in exitBreakPlugin.ts add various hotkeys for breaking out of a block." (The respective purposes of the exit break, soft break and reset node plugins were particularly confusing to me at first.)

[wfischer42]

One of the things I struggle with most when working with Plate is not knowing what helper functions are available for me to import and use.

I second this. It sometimes takes hours to parse through exactly how Plate implements some plugin so I can almost replicate it, and it's one simple line of code to a helper function.

If you want to use Plate exactly as it's built, the docs are almost useful. As soon as you want to lift state, or override functionality in a specific situation, or use plate-headless and provide your own interface for existing plugin functionality, the developer experience can get pretty bad.

It seems to be as much a matter of documentation philosophy as it is completeness. I'm just as interested in documentation that explains how it works and how to customize it as I am in documentation about what's available and how to use it. Slate has lots of that kind of documentation. There's so much really good code and functionality in Plate, and it could be a very powerful solution, but without a glimpse of how to use it to make and customize awesome plugins, Plate eclipses much of the flexibility and unopinionated-ness inherent in Slate.

[zbeyens]

Thanks for your feedback @wfischer42, Plate is indeed in a state where you need to dig into the code (as Slate is at some point). Global adoption is not yet the priority. Too much effort into maintaining the API can kill the project so we definitely need to define a smart strategy as the first step:

1. What do we document? The more we put, the more it becomes difficult to maintain.
2. Instead of copy/pasting the JSDoc, can we generate it? https://plate-api.udecode.io/ is a first attempt that we can probably optimize.

A few of the next steps for the APIs documentation are:

1. [P-202] Slate Utils #2245
2. Divide the APIs by layers (from the most important to less important to document)
3. Documenting the most important APIs
4. Ideally, examples for these APIs (e.g. using https://emeraldwalk.github.io/slate-playground/)
5. Grouping them in interfaces (as Editor, Transforms, etc. do) for better retrievability

[wfischer42]

Those are good points.

Maybe the simplest place to start is to make the current documentation set a little easier to read by condensing the current examples into fewer files:

the large number of source files used in each of the current examples makes it hard to figure out what's special about that example in particular.

The trouble with the way it's currently structured is that tabbing around to see how things are wired together takes a lot more cognitive bandwidth than seeing more of it on one screen, especially since much of that time is spent just trying to find the tab to switch to. Higher "context density" makes it easier to understand (incidentally, that's why large monitors make programmers more productive).

On top of that, it would help to separate less of the code out into separate functions. The existing examples would be easier to understand if they were less modular. It's great code style for the application itself (dry, single responsibility, encapsulated), but harder to navigate and understand in a documentation context.

Is something like that viable for improving current documentation readability without introducing extra overhead?

[zbeyens]

This is a great way of defining the first APIs to document, I'll assign this to @tmorane

[12joan]

I found this cheatsheet pinned in the Slate Slack. Updating it for Plate and adding it to the docs might be a good idea.

[zbeyens]

I'll close this one as completed.

See the new docs in https://platejs.org/.