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
- 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 :]