Over the course of the summer (and beyond) I plan on working a bit towards improving the documentation.
As such, I’d like to ask:
Are there any documentation pages you feel could use some attention?
Are there pages that don’t currently exist but you feel like they should be available in the documentation?
Please let me know of any docs pages you’d like to see revamped, and any suggestions you have for improving them.
If the page already exists, also leave a link, if it doesn’t just explain what you’d like the page to be about.
Thank you for the help, and hopefully you’ll hear from me again soon
The documentation for the Livetable Macro could be improved by considering all the help articles in the forum for example. This could be of help for the documentation as a whole. Most questions should be answered by the documentation: “You will find the answer to your question in section 123 in the documentation for XYZ.”
I think you’re using the wrong forum as you’re pointing to some paying apps from the XWiki SAS company (store.xwiki.com). This forum is for xwiki.org and extensions on extensions.xwiki.org
Hi @jmarkoll thank you for this report, I have updated the Pro Macros and Confluence Migrator (Pro) pages accordingly to specify that task-list and task-report macro are part of the Task Manager (Pro) application. However, as Vincent pointed out, it would be best to discuss about XWiki SAS’ Pro Apps on our dedicated repos or by offering feedback on individual apps.
Hi! It’d be great to have more info about velocity macros from the Frontend Resources page.
Just today I tried to figure something out, but it dawned on me that there was no easy way to find out about velocity macros provided by default in XWiki:
I did not check but the list containing only ten macro seems suspiciously low. It should contain all of the current macro and I doubt it’s been properly updated in a while.
Of course let me know if I can help with any of those documentation updates (I’ll probably spend a bit of time improving the situation of what I discussed above soon ).
I think you might be interested to know we have a community day dedicated to documentation improvement planned for the 28th of November. It would be great to have a list of critical pages to fix for people participating by then.
Thank you for this initiative!
Have a good end of the day,
Lucas C.
It would be great, if some of the help-scripts (groovy, velocity) could be placed in the documentation to get a hint where to look in case of erros, like this i mentioned in my thread regarding shortURLs:
E.g. in a separate section for debug-infos:
which modules are affected, so we can set the loglevel only on the relevant ones and not set “debug” for whole xwiki
some of the velocity/groovy scripts to get the “effective” settings easily
Just throwing the idea out there, I didn’t check feasability, but we might also be able to set up an app on our documentation wiki to retrieve documentation update requests. A forum topic is good to get a lot of input , but on the long term things will be easier to keep track of with an app.
The Front end resource page is about javascript and CSS
Velocity macros are backend macros, not for front end dev
What am I missing?
I started documenting this but i didn’t get much help back then so i only started the work Note that not all velocity macros must be documented as several are internal and not supposed to be public/used.
That’s actually great news! I’m sure we’ll get a lot more entries by then.
I’ll also ask for a list of the most visited pages according to google analytics and I’ll add them here as well.
@gabrielc FYI we also have a lot of jiras created at Loading... for missing doc or doc to improve. This is where we register doc work to do for xwiki.org.
Front-end resources are mainly composed of JavaScript libraries, CSS stylesheets and their corresponding HTML reusable snippets (or velocity macro to output this snippet) and velocity macros.
This is probably the confusion. For me the front end resources page was about client-side resources (ie only javascript and css).
I don’t think it makes much sense to have in it everything that is used to generate HTML pages (in which case, it would contain XWiki rendering, all vm files, a link to the architecture at https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Architecture/URL%20Architecture/, and a lot more). In any case it’s a choice and we need to decide how we want to document all this.
Yes, we can provide a bit more detail. A first step is to define how we document an internal macro vs a public macro in macros.vm (this requires a separate thread). Here’s an example of an internal macro (but there are plenty more, not marked as such):
#**
* Internal macro - Determine the name to be displayed in a livetable's column header. Strategy is as follows :
* - If defined, the 'displayName' passed as a column option wins.
* - If not, and if a i18n prefix has been passed, we use the localization tool with the prefix + the column name.
* - Finally, we fall back on the column name.
*
* @param colname the column name
* @param colprop the column properties map
* @param transprefix the translations prefix to use
*
* @internal
*#
##
#macro(getLivetableColumnDisplayName $colname $colprop $transprefix)
#if("$!colprop.displayName" != '')
#set($displayName = $colprop.displayName)##
#elseif($transprefix != '')
#set($displayName = $services.localization.render("${transprefix}${colname}"))##
#else
#set($displayName = $colname)##
#end
$displayName##
#end
I thought you were working on defining what’s an API for javascript and CSS. It seems you’re also including other stuff (which is good since it’s needed):
velocity macros
vm files (when is it an internal one, when is it something public that can be overridden in a skin). I don’t think we’ve defined this clearly (needs another thread). Maybe they’re all public but in this case, we also need to define what’s the process for removing some or introducing new ones, ie how we handle backward compat
So basically we need to define for all non-java resources:
BTW @gabrielc when you make doc changes, please always using “minor edit” checkbox unless you’re making important content changes. Otherwise your changes will swamp the news unnecessarily at https://www.xwiki.org/xwiki/bin/view/Main/News (and cause unnecessary notifications too). Thx!
and maybe also that someone should use table headers at all (Brainstorming: Enforcing table headers) maybe with some explanation why you should use this (technically neccessary or better readability, …).
and so on…
I would use this information to create/adapt the templates, so every user in my xwiki will use them (most of them don’t change much in the structure of a page).
Now I’m doing the templates as i think it’s the easiest, not taking care of anything else (compatibility with future versions, …). And if all of such suggestions are on one place, i’ll also find some other things i could improve in advance…
).
, but on the long term things will be easier to keep track of with an app.
Note that not all velocity macros must be documented as several are internal and not supposed to be public/used.
. Will do in the future.