so this topic title is a bit provocative but it sums up my current feeling about those pages.
We currently bundle in XWiki Standard two applications Help and Sandbox. Advantage is that it allows anyone to immediately have documentation about a deployed wiki without needing to go online, it provides examples and toy apps for Help, and a first Sandbox where anyone can play.
Now I can see at least 2 problems:
we don’t properly maintain documentation of the help pages, or new features in sandbox pages: we generally maintain more those information on xwiki.org as part of the standard doc we keep up to date along with the releases
those pages are complicated to translate throught Weblate as they contain specific XWiki syntax and it would be a huge work to have Weblate support XWiki syntax
So the proposal here would be to consider that those pages are only available in XWiki.org, and that they would be translated also here. Then it would be easier to maintain them up to date, with the help of the community. And performing translations might be easier on the long run as there’s a few new extensions related to translations inside XWiki, and also for those pages we’d be inside XWiki so no problem with the syntax.
We could decide that we start globally to encourage translators to translate all doc on xwiki.org.
For toy apps we provide in Help, we could decide to still bundle them in XS, as it’s probably something we want people to be able to play with. A solution would be to still have a Sandbox page, very minimalistic, and the toy app provided along with it.
We’d still need a help page to provide pointers towards xwiki.org probably.
And finally we might still need an easy solution for allowing users to bundle the doc page in an install: I’m thinking that maybe we could provide a mechanism to allow installing some xwiki.org doc page from the extension manager. Without having to perform actual releases of the doc pages. And that could be used also for offline installs (i.e. to be able to use the same mechanism to produce a XIP).
Hey @surli, sorry I missed this post originally, but thanks for linking it to my proposal.
Honestly, I don’t know exactly what is the problem that the Sandbox app solves. By its name, I get that it is a place that I can create content and play around to see how XWiki works, but how that’s different from creating a new blank page and play on that one. Honest question here, I really don’t know the difference.
+1 from me to remove it from the bundle.
Now the help. I get that it is bundled for contexts that the user might not have access to the internet fully, like behind a proxy. But the app itself contains links to external docs anyway. And some that are not external are usually a link for the feature itself. Example: “Page Editing” leads me to edit the Sandbox page, and when I go back in browser history I don’t go back to help, but to the Sandbox app, very confusing.
+1 as well, but I agree that it would be important to have something to offer to Admins to make the online pages available offline.
If you create a blank page and put “crap” in it then you’re defacing the wiki. Don’t forget that it’s in production usually. Basically the sandbox space is a space dedicated to trying out stuff and thus known from all to be about that.
If we had personal pages, they could be used to try out stuff (but not in a collaborative manner so we’d still need a sandbox space).
We also use the sandbox pages as documentation for basic features.
Last, having a sandbox page is historically a concept that all wikis had.
I don’t have a definitive opinion on this yet, but here are some points that might be against the proposal:
xwiki.org is currently not multilingual and making it multilingual creates a significant maintenance burden and questions like which parts of xwiki.org should be translated - the main page, documentation (which parts), extension documentation (currently impossible), news (the blog, also impossible), …? As multilingual in XWiki is far from polished, it will also create new usability problems on xwiki.org.
The help application contains a list of all macros (in XWiki.XWikiSyntaxMacrosList) that are available in the current installation, this kind of documentation cannot be provided on xwiki.org.
I agree that structure of the help application feels strange with links pointing everywhere from local documentation pages to the actual editor (for editing) to xwiki.org with seemingly no system and that it isn’t properly maintained. Still, I think a bundled help application has value that cannot be provided by an online documentation.
Regarding the sandbox, yes, having a pre-configured space that already demonstrates some features can be easier to play around than a blank page. Further, the sandbox is nicely excluded of the main navigation and thus doesn’t “pollute” the main wiki. Yes, all of this can be easily created by somebody who knows XWiki in five minutes, but it will be much less obvious to somebody who doesn’t know XWiki.
I see that a bit differently. For “which part should be translated” I’d say all of it if it’s possible, but we can start slowly with the pages the most accessed and probably what is already translated in XS.
On the stability part, my opinion is that it would push us more to fix the problems related to translation in XS which is a good thing. And I agree not being able to translate extension doc is a big issue, but that’s something we could decide to work on.
Here I’m not saying that we should get rid of the help app right away, but more proposing a direction to go to.
I missed that, now I’d be interested to know who is actually using that page? It’s not a page easy to find, and most of the info it provides are actually shown in the WYSIWYG editor when inserting a macro.
We have decided a long time ago that we didn’t want to have translations on xwiki.org even if we have users saying that they’re interested to help out. The main reason is that of quality of the translation for our users.
A translation requires a lot of work as it means:
Ensuring that enough is translated and not just a subpart
Ensuring that there’s always enough translators available for a given language
Ensuring that for any change to the EN language, the translated page are translated very soon thereafter, with a mechanism to signify to readers that the version they’re reading is not up to date in the meantime.
Some way to validate the quality of the translations since it affects the quality of the XWiki software and thus affects its reputation.
It’s not too hard to translate the XWiki UI since there’s in practice very little to translate. However, translating full doc pages on xwiki.org is another challenge and another complexity level.
If we wanted to go in this direction, we’d need a plan and a LOT of tooling developed (automate creation of screenshots of XWiki in various languages for example to give just one example).
Knowing that we already have a very hard time to maintain the documentation in English (it’s never up to date with the software, especially screenshots - to give an example, the page that is one of the most viewed one on xwiki.org, the “Getting Started” page, is out of date - BTW @surli it might be nice if you could update it since it’s a change you made with the new notification menu that made it out of date OTOH I’m still not 100% sure if the new menu is a good thing on the long run but FTM I guess we should consider it is).
So for me, I’d still prefer to continue our policy of not translating xwiki.org and to focus our energy on improving our doc there instead.
On the topic of not bundling sandbox, I think I’d prefer to continue bundling it by default. It’s always possible for our users to remove that extension.
What we could improve/discuss:
Introduce a DW step to perform more configuration and let the user decide what they want/don’t want, for ex give the user the ability to add or remove some extension at install time.
Make it simpler for users to realize that they can remove a feature such as the sandbox by uninstalling it. We need to brainstorm about it (info in the Tour, message displayed the first time you navigate to the Sandbox home page with a link to uninstall, etc).
Think more about the sandbox scope and move some of the content found in the Help app to the sandbox, for example to play/create AWM apps there, try more macros and apps there, etc.
Various XS versions and the doc is only for the latest version
Quality of the doc on xwiki.org. Maintaining the quality of the help app doc is not the same as maintaining the whole quality of xwiki.org for all topics for its thousands of pages.
Sure, but I don’t really agree that the points you mentioned are real issues.
Why would it be a problem that only a subpart is translated? It’s what we have in XS for some languages. IMO that’s not a problem if let’s say some pages only are in french: it’s already that doc that will be available in french.
I also don’t understand why it would be a strong need, for XS we surely don’t do that.
That’s true for XS too and we mostly trust the translators.
Remember that I started this whole topic because we currently have in XS full pages that we ask our translators to translate on l10n.xwiki.org and it’s a problem for us. The whole idea here is to move those to directly translate them in XWiki and more specifically in xwiki.org.
I don’t understand this part, or maybe there’s a misunderstanding somewhere: I never suggested to get rid of Weblate for translating XS. I’m only talking about translating the content of xwiki.org, so I don’t see why we’d need screenshots etc? It’s about translating wiki content.
That’s another interesting argument, but for me that’s not the same people who will improve the doc and those who will translate it. So I don’t really think it’s a problem for that.
I agree it might be more a problem to actually properly maintain the platform, since as Michael exposed, we might find bugs etc related to multilingual. But as I answered above for me it can actually be interesting to improve the platform on that aspect.
By subpart, I meant if the doc was not fully translated.
A bit of context, in the reply you quoted, I was not replying to the topic of translating the help app pages or the sandbox pages but I was replying to the general idea of translating the whole of xwiki.org.
Because if you don’t have enough translators then 1) your translations are never up to date, 2) users will rightly complain that translations are missing content/quality. Globally it’ll lower the quality and seriousness of XWiki.
Don’t forget that we’re talking about allowing to translate the whole of xwiki.org here.
I explained above why it wasn’t the same problem. Copy pasting:
It’s not too hard to translate the XWiki UI since there’s in practice very little to translate. However, translating full doc pages on xwiki.org is another challenge and another complexity level.
Again not the same complexity level at all.
That’s not what I was discussing in this reply. See what I quoted:
Regarding the help + sandbox pages, I think that we have solutions to make it simpler to translate them on weblate and we don’t need to make the whole of xwiki.org multilingual. In addition it would be inconsistent to have 2 tools to translate the UI of XS (weblate + xwiki.org). Better have all of the translations in one place.
Because xwiki.org pages are full of images. And whenever an image is updated for 1 language, it’s just impossible to expect it to be translated manually and quickly in all the other languages. Thus, without tools, you’d always have very bad quality documentation in translated languages.
It is the same people who improve the doc on xwiki.org and who would also develop the tooling to make translations doable and to explain the bad quality to the users.
OTOH I’m still not 100% sure if the new menu is a good thing on the long run but FTM I guess we should consider it is).