As decided in T258953, we will represent the documentation of ZObjects not in JSON, but in a second MCR slot. This task is for implementing that system.
The wikitext is stored in the second MCR slot, for all languages. The ZObject handler looks the slot up, gets the appropriate doc from the slot, and displays it between the Header and the actual ZObject rendering.
We also need to implement how to handle editing, history, watchlist, etc.
| Status | Subtype | Assigned | Task | ||
|---|---|---|---|---|---|
| Open | None | T260953 Implement a full multi-lingual wikitext documentation system for Objects (for more detail than just the short description system) | |||
| Open | None | T260954 Store documentation for ZObjects | |||
| Open | None | T260955 Edit documentation on ZObjects | |||
| Open | None | T260956 View documentation in ZObjects | |||
| Open | None | T304904 Create a design for having and interacting with multi-lingual documentation on ZObject pages |
I'm guessing that "MCR slot" is referring to Multi-Content Revisions. From https://www.mediawiki.org/wiki/Multi-Content_Revisions/Glossary:
- slot: the association of a content object (documents) with a specific role in a given revision
- main slot: the slot with the "main" role. This is always defined for any revision, and is always a primary slot. It will be used per default in places where legacy code expects only one content object to be associated with a revision.
- derived or virtual slots: these refer to the idea of respectively storing or generating content derived from the primary user-supplied content.
- content: a self-contained document, representing the information associated with a slot.
- primary content: content that is user-created and cannot be re-created from other slots (e.g. the article text). The primary slots of a revision can be enumerated.
- derived content: content that was derived from content in other slots and is not user-editable (e.g. a blame map)....
From the above, it still seems to be an open question which (kind of) "content object" should have the "main" role. As I said in my email of 2020-07-29:
I think we do have "secondary wikitext" but it might be implemented as "primary wikitext" with secondary translations as sub-pages (somewhat optionally), as in Meta.
Reading the Description here, it seems that this is not what is proposed (which is fine; no doubt there are good reasons) but it is not clear whether it should be the documentation that has the "main" role or the JSON. What is the "primary user-supplied content"? Clearly, it is not the JSON, since that is always derived from some process that deliberately conceals its stored results (the JSON)...
For the record, I re-state here the constraints I suggested should apply (in my email):
Constraint 1 is that text entered by humans must be stored as human-readable text.
Constraint 2 is that text is bound to its context.
It might reasonably be argued that choosing an option from a dropdown is not entering text but is a mechanism for entering an underlying code, so it is okay to store only the underlying code and not the label for that code. Maybe it is okay, but I advise against it, especially in an immature, multilingual context. The spirit of my first constraint is that a human can always see later what was seen (or could have been seen) immediately before it was stored (the "Urtext"). Encodings may have changed in the meantime, and such discrepancies could usefully be highlighted, and maybe the Urtext should not be the default view... but the Urtext MUST always be available. In what sense, then, is it not primary? And in what sense is the JSON anything other than derived?
May be related, we have two fully translatable pages on the wiki:
The second item may need significant revision over time but the first one should be almost OK, unless there are drastic changes required, and minor things (like the name of the project and showing the new logo once it will be voted).
This task is more general hwoever and does not speak only about builtin objects needed for the bootstrap, but other objects that will be constructed by contributors and that will need tools for documenting them.
Even if this Phabricator site is essential for now, it should still not be used as the only link with the community that must be informed, starting by a wiki which is the tool they all know (Phabricator is difficult to use for many, and too technical for discussing many points).
The project must be explained early, so that decisions can be validated and changes brought before its's too late. A recent example occured with the precipated use of a new voting tool that was not properly tested but deployed without correct testing with the community, notably with users have Arabic or Hebrew names, or voting within a page visited with a language preference for RTL: the Bidi layout must never be forgotten for this project that must be multilingual from the start, and not jsut oriented towards English (like everything here in Phabricator).
So please include users in your project that will make at least a test in Hebrew, Yiddish, Arabic, Persian, Pashto, or Urdu for everything, notably for the layout, usability. I can help on many things and I have done a lot to prepare almost all wiki pages for their translatability, but we must not be required to make urgent decisions in jsut a few hours without proper testing, and block immediately the features in their state, even if it was not tested at all, so that it was even impossible to fix it (or a XMF user reverted the changes on a single page before the tool was even deployed with an alpha test that could be elabled; there was no alpha, no public beta, this became instantly frozen and live! I think this is in contradiction with the announced goals of the project, and there's no reason to consider this was "urgent").
So establish a more reasonable scheduling for deployments: there's no reason to instantly switch from a very long early discussion period, to instant deployment of things that were never discussed before. A reasonnable test period of at least 1 week for the alpha (with some instruction to activate the test and report bugs or suggest/compare alternatives) and 1 week for the beta (with a public test) is needed: the final features can be delayed so that users and developers can decide what is critical or what can be postponed to deploy a more limited version.
Otherwise you'll introduce severe quirks and criticisms fro mthe community and the initial appluaded project could be defamed rapidly., with many peopel loosing their interest in it or changing their mind to an opposition that will be much harder to reverse: it could mean the abandon of the project and loss of all the work you've already done.
Usability is a key part of the project (in addition to reliability and security: this should not overwhelm adminsitrators with too much work to repair things after facts, as many of them would also decide to abandon their support of this project).
@DVrandecic A priority as extreme as "unbreak now" for an otherwise normal task appears to be a mistake. See https://www.mediawiki.org/wiki/Phabricator/Project_management#Priority_levels.
This look like a Medium priority task to me. It's not that important, but not too important to warrant High priority.
@AnotherEditor144: Hi and welcome. Please see https://www.mediawiki.org/wiki/Phabricator/Project_management#Setting_task_priorities and do not change priority. Thanks.