[Discussion] Unifying Documentation and UI-Based Editing

September 22, 2019 21:05 marandall@php.net (Mark Randall)
Hello all,

After participating in various conversations, and listening to the most 
recent PHP internals podcast about moving the documentation to GIT, and 
the problems with editing, I spent most of the weekend knocking up a 
prototype that I want to present as a possible solution to these problems.

The prototype is available at https://php-doceditor.markrandall.uk/ and 
has some basic functionality. I must stress it is far from complete.

In this PoC I attempted to solve the following issues:

** 1. Difficulty in editing XML **
Something I hear a lot is that the XML format is difficult to work with. 
The format clearly has its benefits, after all almost all the web is 
written in it, but I think for something like the documentation, a UI 
based editor would be a superior mechanism.

To that end I created a front-end for editing the files, or rather, a 
converted format of the files which takes the XML and ports it into 
JSON, which is programatically MUCH easier to work with.

It in effect still deals with nodes, but they are abstracted out to 
nested UI elements.

** 2. Immediate Visual Feedback **
The process for re-creating the documents once they have been uploaded 
to SVN is not an instant one. I wanted a way for the editors to be able 
to see what they would get, and so I provided a very simplistic 
Javascript based renderer.

Naturally it will need a lot of additional work to include all of the 
features we would require of it.

** 3. Translation **
This is perhaps the biggest and most controversial of suggestions. At 
present, various translations are kept in completely independent files 
where the structure is re-created in each one.

My proposal and demo turns this on its head. Rather than using multiple 
files, all languages will coexist in a single document that will 
simultaneously act as both the template, the English source and its 

To achieve this I have introduced the idea of text sections. These are 
effectively containers for a set of paragraphs or examples. Crucially, 
each text section will contain effectively the same text, but in 
multiple languages.

This means that text that effectively says the same thing, will be 
stored next to each other. As you can see on the example, it is easy to 
open both the French and English editing boxes at once.

** 4. Translation Synchronisation **
Following one from the UI element of translation, as I understand it, 
one of the biggest problems with moving to GIT is needing to store 
hashes so that the system knows what information is out of date and by 
how many revisions.

The ability for the UI to add metadata to the text sections eliminates 
this problem completely. I propose that each translated section would 
have a button displayed that would indicate that a major change had been 
made, which would update a modified timestamp in the respective 
language’s JSON object for that section.

This would allow easy comparison of when translations were outdated. The 
renderer, having access to all known translations at once, could 
potentially give warnings that a given section was wildly out of date, 
and offer to display the English or other more recent version inline.

** 5. Improved Type Information **
With the almost certain addition of unions in 8.0, the types for 
parameters and return types are becoming much more formalised.

Rather than just expecting one type, I have designed the prototype to 
allow specifying multiple parameter types, and multiple return types, 
and providing distinct information for each, with the UI adjusting 
accordingly when union types are present.

Pre-Emptive Q&A

1. Why do certain blocks have the ability to add multiple text sections?
This was a design choice to help with translation. While it would have 
been possible, and frankly easier to make each major part only have one 
translation for each, these could become quite large, and I think it 
makes sense to split them up.

Therefore, sections like notes and examples have the ability to extend 
themselves with a multiple text sections, where each one is tracked and 
translated independently.

2. But I love XML
At present, I have only made a one-way conversion process that takes XML 
and turns it into the necessary JSON for rendering, and it’s my 
intention to improve it some to be able to pull in existing translations 
from multiple languages (using common identifiers such as a parameter 
name as a point of reference to join the data).

It would be possible to write something that did this in reverse, and 
took the JSON and turned it back into valid Docbook XML. If this makes 
any sense in the long run I am not convinced as I think writing the 
renderers is a lot easier in JSON, and it can be committed to GIT all 
the same if it's pretty-printed so it's not all mushed up on one line.

3. Validation?
Definitely needs to have JSON Schema applied to it before it's put into 

4. Source?
Sauce? Tomato Sauce? https://github.com/marandall/phpdoc-editor

Avoid the XML parsing code. It's pure cancer.

Mark Randall