For a great technical writing experience there are a couple of things that needs to be considered:

• Support of Tables

• Support of preformatted text and inline code

• Support of emojis

• Support of Graphs

At the beginning of Artidoc, Ckeditor 5 was selected mainly because it was the successor of ckeditor 4, already end of life. However we had to revert this change because it was not possible to have both versions of the editor in parallel (artifact view v4 and artidoc v5) due to HTML format change between the two versions. In additon to that, it felt easier to have the image support in v4 than in v5 because we already did it elsewhere.

Now Artidoc v1 is out there, it’s time to get back to Rich Text Edition selection.

Why do we need to change:

• Ckeditor 4 is end of life

• The edition experience is not great. Having to manually switch to edit mode is painful when the documents are long: we scroll down to read, identify something to change, scroll up to switch to edit, scroll down again to find the right place where to do the switch. It's also made painful because there is no sub-heading in the Section (eg no 1.a that would correspond to first <h1> in the artifact description). Hence we cannot scan easily to find the right place where to edit.

The scope of this story is to evaluate the alternative we have right now and to produce an Architecture Decision Record that will detail which solution was selected and why.

The editor must have

• formatting (bold, italic, lists, quote, links, code blocks, inline, exposant...)

• headings (titles, subtitles, etc)

• images (copy/paste and drag n'drop)

• tables (including copy/paste)

• keyboard shortcuts (eg typing `*` starts a new bullet list)

• must not interfer with browsers native capabilities like spell check

• HTML paste

• select text and have the ability to attach a comment to it

The editor should

• allow to have the artidoc in transparent edit mode or offer a usable alternative (cf problem of scroll described at the beginning)

• include graphs (hypothesis, graphs will be done externally using draw.io and then included in the RTE but the navigation between the two contexts should be as seamless as possible).

• have the possibility to support realtime concurrent edition

• support Tuleap specifics like typing art #... and have a link. In the futur we might also imagine that it would trigger an autocompleter.

Not mandatory / can be challenged

• ability to deal with conversion text <-> markdown <-> html

Things to keep in mind:

• There is a strong need of diff, including inside tables. It should be possible to produce one (between two versions of the document or between two documents) but its not mandatory that the RTE should manage the diff.

Editor tests:

General concerns:

• Yjs-websocket documentation for Realtime

• tuleap tooltip (like art #38627) can be supported on every editor and needs a specific development to support mention art #123, transform them into an updatable link

• draw.io integration has no impact on editor choice

• markdown support is not a requirement here, we need to have an editor who is smooth for editing and not developper oriented like

Milkdown (doc | examples | other example | code | playground):

✔️ Good

• easy to start

• doc and examples seems accessible

• it comes with almost everything we need, and code integration seems easy `npm i plugin` and `.use(plugin)` in code

• tested plugin are supported by editor and not the community

❌ Bad

• does not support typographic replacement `(c) (C) (r) (R) (tm) (TM) (p) (P) `

• does not support emoticons `:-) :-( 8-) ;)`

• the toolbar is provided by an external plugin not supported by milkdown team, I did not want to spent lot of time on it, it seems to do the job, but I didn't see anything to support link and/or image.

  • The copy/paste of image and the dnd looks good enough for me but to be checked

  • the official way of making link is by hovering text and adding a link (storybook)(code). I find this usage a bit hard to discover for our users

  • /!\ we need to write css for the toolbar

📑 wysiwyg needs

• ✅ Support of Tables (preset-gfm)

• ✅ Support of preformatted text and inline code

• ✅ RTE

• ✅ formatting (bold, italic, lists, quote, links, code blocks, inline, exposant...)

• ✅ headings (titles, subtitles, etc)

• ✅ images (copy/paste and drag n'drop)

• ✅ tables (including copy/paste) 

• ✅ keyboard shortcuts (eg typing `*` starts a new bullet list)

• ✅ must not interfer with browsers native capabilities like spell check

• ❗ Support of emojis (ok but no emoticons)

• ❗toolbar (needs lots of customisation, css and new custom button, worth probably to write our own toolbar plugin or extension to toolbar plugin)

• ❗ seems to support checkboxes (like in playground), does not work on my POC (probably pebkac)

• ❌ HTML paste

• ❌ select text and have the ability to attach a comment to it

• ❌ anchor/refs

• ❌ support au diff

• writting our own pluging

Other (not tested)

• Open AI integration 

• LaTex support

• ❗mention people and create links (community plugin)

Quill (doc | examples | code | playground) :

✔️ Good

• easy to start

• toolbar plugin is easy to add and configure, seems easy to add new option in toolbar if needed (like done by emoji plugin)

❌ Bad

• markdown support is low, It does not display image ou table

• does not support typographic replacement `(c) (C) (r) (R) (tm) (TM) (p) (P) `

• does not support emoticons `:-) :-( 8-) ;)`

• emoji plugin is outdated, no update since 2021, I have build issues (due to es6 module)

• every plugin I dig into is outdated, I don't think we can rely on external quill plugins

• even plugin list powered by quill is outdated

📑 wysiwyg needs

• ✅ Support of preformatted text and inline code

• ✅ RTE (seems ok over yjs code + demo)

• ✅ formatting (bold, italic, lists, quote, links, code blocks, inline, exposant...)

• ✅ headings (titles, subtitles, etc)

• ✅keyboard shortcuts (eg typing `*` starts a new bullet list)

• ✅ must not interfer with browsers native capabilities like spell check

• ✅ toolbar 

• ❗Markdown support is less complete than milkdown

• ❗ Support of emojis (outdated)

• ❗images (copy/paste and drag n'drop), lib is not updated even dependencies since a year

• ❗select text and have the ability to attach a comment to it (found an example, little bit broken, but can be a good start) 

• ❗support au diff

• ❌ tables (including copy/paste) seems not ok, plugins are outdated, no maj since several years

• ❌ HTML paste

• ❌ anchor/refs

• writting our own plugin

ProseMirror (doc | examples | code | playground) :

✔️ Good

• modern editor like milkdown or tiptap are an overlay of prose mirror, we should be able to have the same coverage than them

• enables us to customize everything

• we'll be able to concentrate fully on user experience we want to provide to end users

• does not comes with css, we'll have to write our own (probably a good thing, we'll be able to make it tlp like)

• undo/redo comes for free, don't know if it's a need, but i find it handy

• y-prosemirror: Yjs integration for real time for code mirror

❌ Bad

• we'll need to implement almost everything, it will cost developpement time, even when we'll try to have same coverage than ckeditor

📑 wysiwyg needs

• ✅ Support of preformatted text and inline code

• ✅ toolbar ("easy" to add our own actions)

• ✅ formatting (bold, italic, lists, quote, links, code blocks, inline, exposant...)

• ✅ headings (titles, subtitles, etc)

• ✅ must not interfer with browsers native capabilities like spell check

other needs who can be supported

• ✅ RTE, as we managed to test it over milkdown, should be ok here, plus there is a full functional demo here, with associate code

• ✅ Markdown support markdown-it-table 

• ✅ keyboards shortcuts comes with prose-mirror demo code (like `Ctrl+b` for bold or `*` to create a list)

• ✅ images (copy/paste and drag n'drop)

• ✅ anchor/refs, the live editing of Tuleap reference will be possible thru a custom plugin, in POC we reached the state where we can directlly add a new link (by typing art #123, then space key will automatically convert it into a link), algo is not done for editing the link, but the API enables us to replace everything with what we want, it should not be an issue

• ❌ Support of emojis, but we can implement it

• ❌ select text and have the ability to attach a comment to it 

• ❌ support au diff

• ❌ tables (including copy/paste)

• ❌ HTML paste

Jodit (doc | examples | code | playground) :

✔️ Good

• written in ts only

• enables us to customize everything

• we'll be able to concentrate fully on user experience we want to provide to end users

• does not comes with css, we'll have to write our own (probably a good thing, we'll be able to make it tlp like)

• comes with color: possibility to have color on text/elements

• it's easy to add plugins and new behaviour

❌ Bad

• we'll need to write RTE from scratch

📑 wysiwyg needs

• ✅ Support of preformatted text and inline code

• ✅ toolbar ("easy" to add our own actions)

• ✅ formatting (bold, italic, lists, quote, links, code blocks, inline, exposant...)

• ✅ headings (titles, subtitles, etc)

• ✅ must not interfer with browsers native capabilities like spell check

• ✅ tables (including copy/paste)

• ✅ HTML paste

• ✅ images (copy/paste and drag n'drop)

other needs who can be supported

• ✅ anchor/refs, the live editing of Tuleap reference will be possible thru a custom plugin, in POC we reached the state where we can directlly add a new link (by typing art #123, then space key will automatically convert it into a link), algo is not done for editing the link, but the API enables us to replace everything with what we want, it should not be an issue 

• ❗ keyboards shortcuts, seems customizable, not tested

• ❌ Markdown support

• ❌ Support of emojis, but we can implement it

• ❌ RTE

• ❌ select text and have the ability to attach a comment to it 

• ❌ support au diff

Froala :

❌ Bad

• not open source, didn't see it in my first candidat selection

Etherpad :

❌ Badsee

• it's a standalone app, can not be included in artidoc

Plate :

✔️ Good

• playground is awesome

❌ Bad

• it's in REACT needs to build and maintain an other js framework

• question about how the collaboration edition is supported, as there is no RTE demo yet

Tiny MCE && tiptap

• Features we need are not open source

Conclusion

• due to our customization and real time needs we choose to use ProseMirror

• as described above, we need to write some code in order to have the same feature coverage than ckeditor

• we will lose the possibility to switch from markdown to html to plain text

MVP to reach ckeditor features

• having a toolbar, and choose how we display it (note toolbar comes without css, we can customise it tlp like)

• copy/paste | dnd image

• references support (type art #123 should create a link, /!\ editing link)

• save and load data

Identified risks

• references support

• table

• attaching comment to a line/text, we will have same challenges than we had for code mirror in pull request (position of comment, comment at the top/bottom). Plus in term of functional what is a comment? can we close/hide it? can we reply to it ?

Others

• we should think quickly about which shortcut we re going to support in editor, it comes for "free" for standard toolbar option 

• how do we handle tooltip for tuleap reference ? (what do we display when we havoer art #123)