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
translations.

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
   use.

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

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

--
Mark Randall