Planning new documentation

So ProseMirror is not, unfortunately, one of those libraries you can install, then quickly glance over the readme, pick out the function you need, and move on. It’s a complicated, subtle monster. For good reasons, mostly, I hope, but this does mean that we have a bit of an education problem. Half of the questions asked on this site are about people not understanding a given assumption or constraint in the system, because I never wrote it down.

So I’m planning a new guide, which will replace the current one. It is intended to cover more material, put a bit more effort into explaining concepts. I am also planning to flesh out the examples with a lot of small examples describing how to implement certain common things (which will hopefully provide a frame of reference for people who want to implement similar but different things).

The reference guide will stay roughly as it is, though I probably will flesh out the descriptions of some important elements a bit, and try to add some glue text to make it somewhat more readable.


Here’s my current outline for the guide:

  • Working with documents

    • positions
    • pesistent updating
    • steps
    • transforms
    • mapping
  • Transactions

    • rationale
    • steps
    • metadata
    • atomicity/composition
    • filtering/appending
  • The view

    • setup
    • props
    • selection
    • node views
    • decorations
    • dom listeners
  • Extension and customization

    • commands
    • simple plugin example
    • history plugin
    • input rules
  • Collaborative editing

    • concepts
    • convergence
    • example code

And these are some simple examples I think would be useful (in addition to adding some prose to the existing examples that explains how they work):

  • Defining a command
  • Building a schema from scratch
  • Setting up a simple node view
  • Adding a floating menu
  • Handling asynchronous file uploads

Suggestions for other topics, and pieces missing from the above outline, are very welcome.

7 Likes

What I’d love to see as an example is background file uploading. This could be used for some other async actions as well. What I mean with async is the following. An image is selected from the file explorer. At that moment some progress bar is shown at the position of the cursor. While uploading I still can edit the text in the editor. When the upload is finished. The progress bar (if it hasn’t been removed during editing) is replaced with the image.

I’ve tried a lot to get this working but still didn’t succeed. I know it can be accomplished with a decoration, but I can’t get a reference after the upload has started. This pattern could also be used for a lot of other async actions. The example could be generalized as:

  • Set decoration and save some reference to this decoration
  • Wait some time
  • Replace decoration with another decoration

That’s a good one – I have implemented that once, and it worked well, but indeed was a bit involved to do properly.

The best documentation would be one that is guide-focused and example-heavy. Don’t go with “simple examples”. Go with extensive examples. Show alternative approaches, explain reasonings, mention gotchas, point to next steps.

I’m massive fan of Django’s docs, because they are obsessively focused on providing reasonable and as close as possible to real world usage examples for anything they are documenting.

Looking at PM’s docs, I would try to be as focused on possible goals of person reading it and avoid going academic. When I was making my first approach to PM’s Getting Started, I’ve noticed that it was quick to drop bulk of at time unnecessary implementation details on me, but took it’s sweet time to explain to me, why enter key is not breaking my paragraph into two. This goes against people expectations.

Ultimately, the docs should be split in three parts:

  • First steps
  • Guides
  • API reference

First steps should show user how to get to basic editor with toolbar, bold, underline, url, image, hr and blockquote. Get or set its value from/to JSON, Ultimately, writing custom editor is complex task no matter how you’ll look at it, so I would assume that user is willing to invest few hours to get trough this tutorial.

Guides should focus on priming users to achieve more specific goals when creating their editors and focus on features and examples, mentioning prosemirror’s APIs as they are of interest to the user:

  • Toolbars and menus, writing mediumesque toolbar.
  • Writing custom block types.
  • Writing custom inline types.
  • Techniques for displaying additional UI, eg to let user change blank paragraph into image or media.
  • Create placeholder functionality for editor.
  • Hooks for integration with 3rd party libraries? (jquery, at.js, perhaps react.js components are elements in editor?)
  • Handling file uploads, paste and drop.
  • Handling pasted content, be it from MS Word, website or other prose mirror’s instance.
  • Considerations and platform specific problems when developing editor for mobile devices.

The library or framework is only as popular as it is accessible to potential users. There are some amazing technologies around that ended becoming relatively niche due to their seriously lacking documentation Ember.js comes to mind being framework with dozens of features and helpers but documentation covering them all in isolation of the other, leaving the big picture for users to figure themselves.

We as developers love writing code, but in light of the above I think that quality of the documentation should be considered of greatest importance to the project’s maintainers, and its improvement should be continuous and closely tied to work on other parts of the project, instead of being an afterthought only happening because there’s nothing interesting to implement in the code at the moment. It won’t be an shocker for project’s docs to take months of work to get to satisfying level .

I’m hoping that good documentation would result in greater project adaptation, which in turn would result in more 3rd party extensions and guides being written by the community.

Just my 3c.

Still happy to see that weight of work has moved towards documentation :]

1 Like

This is not the kind of library that ProseMirror is – it’s a set of building blocks, not a drop-in editor component. Menu/toolbar functionality isn’t even part of the core library, for example.

So these are just not expectations that I’m going to fulfill – you are going to have to understand a bunch of concepts to be able to work with ProseMirror, and you won’t get a finished editor with a few lines of code.

I still hope someone will at some point distribute a wrapper library that uses ProseMirror to provide an out-of-the-box editor, making their UI decisions for them, but that’s not the library that I’m maintaining here.

1 Like

@marijn That would be awesome :+1: Happy to help out where needed

Would be nice to have some examples on NodeViews

Hey @marijn, just some food for thought…

I’m a senior engineer with a lot of experience working with various web editors, and I really appreciate what I’ve seen of the prosemirror design so far. I think it makes sense that you’re creating the low level primitives with which engineers can build highly custom editors.

But in terms of learning the framework, I’m finding the learning curve to be very steep.

It makes a ton of sense to walk through the basics so that people can ramp up quickly and then get to the good stuff - taking control of a fully customizable editor.

I see a huge upshot to the “getting started guide” walking users through how to re-create a nice “vanilla” editor, explaining how Prosemirror works along the way. At the end of the walkthrough the engineer who followed the examples has (a) a working, vanilla editor, and (b) a good understanding of how and why Prosemirror works the way it does. From there the benefits are going to be really obvious: you now have an editor that you have enormous control over, you can see where all the hooks are that you’re going to want to customize, etc.

From reading a lot on the forums it seems like your stance is “people should just pour through the code until they figure it out.” I’d just encourage you that guiding engineers into the software starting with the basics is likely to result in a lot more adoption.

Not a fair characterization at all. I don’t think I’ve ever suggested people should read the code to figure out how the library works, and here we are in a thread that is about me working on improving the docs.

1 Like

Hey @marijn, your plan sounds good to me. My own guess is that likely 99% of what people will be doing is a standard editor with all the standard options + maybe a handful of custom elements, so I would think it would be good to make that relatively easily available. Maybe even a built-in way to gloss over the state/view/dispatch stuff so that only those who rally need to make use of getting their handsdirty in there need to touch that and everyone else can treat it as a simple event based editor. I think you mentioned earlier that it should be possible to make a package that does that. It could increase the number of potential users and flatten the learning curve a bit.

As for documentation, I have found myself to have changed slightly how to find out about how to do things. For version 0.10, I would be reading the reference guide and look through my local copy of pm to find the functions I need. At times I would also just poke it in the browser’s development console to find a useful variable. For version 0.22, I read a tutorial, I consult the reference guide, but mostly I use the search function on github to look through all the prosemirror repos, trying to find examples of how a specific function is used. And it’s not always that there is a lot there, which is when I go to the forum. So I think real-life examples of PM usage on github would be a useful resource.

I don’t see how this is exclusive from what I’ve written.

Does this also render all other points I’ve raised as void in your eyes?

No. Did I say so?

No, but plenty is lost on the internet, so you never know. :wink:

Great, this is good news.

I think a bunch of people like me would be interested to use Prosemirror along with other frameworks such as Express, ReactJS and for collaborative functionality using Mongodb database, Socket.io etc. I think some guide or examples on integrating Prosemirror with popular frameworks will greatly help in improving adoption.

That’s probably a great area for the community to help – I have neither the experience with the systems you mention nor the time to write these, but if you find yourself wiring up ProseMirror to something else, writing a blog post or an article on the project’s github wiki is probably extremely useful to people who try to do the same thing.

I can commit to a post on Angular (i.e. not AngularJS) with the basic integration of ProseMirror events into the entire app and some examples for injection of Angular services into ProseMirror views) and a Github repo with the source code.

@marijn Am I right to assume that blog posts written for 0.22 could later easily be labeled 1.0?

Great to hear about this plan for new documentation. I really like the CodeMirror approach, and would strongly prefer lots of minimal examples that can be easily composed together, rather than a “walkthrough” of some particular set of details.

I was able to put together a simple CodeMirror instance in a couple of hours by looking at relevant examples (and then reading the corresponding documentation), but ProseMirror has been less trivial to figure out.

The fact that CodeMirror has a much simpler API is probably largely to blame for this – the CodeMirror docs are very much in the style of the ProseMirror reference manual, but because there are less concepts involved, it’s easier to figure out how it works from just reading about isolated methods.

I just started playing with ProseMirror yesterday and so far it seems pretty good. I think the Schema documentation could use some example as it’s still hard to intuit how a block could look like just from reading it. For example, walking through a figure with caption or a blockquote with a footer.

In terms of tutorials, I’m also looking at Quill and Cloning Medium with Parchment - Quill is a pretty good introduction to many concepts.

You can find the rewritten guide here. The examples also got an overhaul, and I added several new ones.

Nice one! The end of a sentence is missing:

It is recommended to always require at least one child node in nodes that have block content (such as “doc” and “blockquote” in the example above), because browsers will

Regarding setNodeType, it seems a bit weird that it also allows updating the attrs despite its name. Is it not useful to have a separate setNodeAttrs to be more explicit? Looking at ImageView example, I had to open the documentation to understand what it was doing since I was expecting something like changing from a image node type to a image-with-alt node type or something similar.

I understand NodeView better now I think, I’ll have to try putting a React component as one