Page MenuHomePhabricator

Provide documentation about the data format used for editing in VE
Open, LowPublic8 Estimate Story Points

Description

When you write gadgets for VE, you sometimes have to understand the data format used by VE, e.g. when using ve.dm.SurfaceFragment.prototype.insertContent() to insert content. I couldn't find documentation about this format anywhere.
https://www.mediawiki.org/wiki/VisualEditor/Gadgets suggest to set breakpoints and inspect the data in the debugger (which of course works, but doesn't replace a good documentation), and has some examples from which you can learn a bit about the format. https://www.mediawiki.org/wiki/VisualEditor/API/Data_Model/Surface#Conversion has another example, but no complete documentation, either.

Probably I have to write such a documentation myself if I want to have one, but is there somewhere some internal documentation, simple tools to convert wikitext into that format, etc. as a start?

Event Timeline

Schnark created this task.Mar 30 2017, 9:52 AM
Restricted Application added a project: VisualEditor. · View Herald TranscriptMar 30 2017, 9:52 AM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
Jdforrester-WMF triaged this task as Low priority.Apr 4 2017, 7:30 PM
Jdforrester-WMF moved this task from To Triage to TR1: Releases on the VisualEditor board.
Jdforrester-WMF set the point value for this task to 8.
Jdforrester-WMF added a subscriber: Jdforrester-WMF.

The documentation is mostly that which you've identified plus https://doc.wikimedia.org/VisualEditor/master/#!/api/ve.dm.Document etc. (but it changes over time as we improve things).

The official documentation is not well written and this is disappointing.

I have the feeling (maybe wrong) that the Editing team in WMF is still in state of mind that VE is in beta and by not having well written official documentation, it gives more freedom to changes and be less committed to API. This is not bad, as long as it is really in beta state and changes rapidly.

However, as more teams either within WMF/WMDE or in the community want to adapt their tools to VE or add customizations lacking well documentation may be an issue.
To be more specific, I think this is a "soft" blocker for tasks such as T136599 or T150652 and it would be nice to see CX and Wikidata integration in VisualEditor with no need of too much support from the editing team.