Hello @gabrielc, thanks for opening this topic. I’ll be very brief:
Page of each recommended and most usable extensions. Here at least - updates have to be started from images: most screens/images that are present, represent old XWiki UI. For instance CommonMark Markdown Syntax 1.2 in newest XWiki you won’t find section “Configuration” in XWiki Preferences page.
Installation documentation for Windows users. Another example from me - PostgreSQL Installation, nowadays after installing PostgeSQL 16+ user has PgAdmin 4 - UI that allows use to create a database and run specific query from Query tool instead of using old psql command line
Tutorial documentation. Here I’d say the entire Developer Guide space needs updates to be clear and easier for beginners.
It includes a <logger name="xxx" level="xxx"/> code snippet for each logger configuration that needs to be set in the logback.xml file to comply with the OWASP recommendations.
I would appreciate some help with this draft, as monitoring XWiki from a security perspective isn’t exactly straightforward (hopefully just for me)
I must admit that I was quite ambitious when I set out on helping with the documentation rework .
That being said, I wasn’t idle all this time. I just added some proposals to the forum, and I’m eagerly waiting for your feedback.
Thank you everyone for your suggestions! All of them are neatly stashed in my personal notes and I will definitely look at them when thinking about how to proceed further.
While the work is still far from over (like… reaaaaaly far), and I cannot give an accurate estimate to when it will be complete, I want you to know that it is something that I am concerned with, and I’m still trying to tackle whenever I get the time to do it.
This is what I have noted in a table in our company’s documentation:
A setenv.sh file needs to be added in /usr/share/tomcat9/bin/ for the purpose of setting memory (Set -Xms and -Xmx to higher system memory than the default)
Whereas when using Xjetty (XWiki Jetty packages), as the newer Apache Tomcat are not yet fit for XWiki, we don’t have this setup anymore, instead we can setup memory in /etc/environment, in a command line such as this one:
XWIKI_OPTS="-Xmx2g -Xms1g"
or
XWIKI_OPTS="-Xmx2048m -Xms1024m"
Of course, if you think other objects can be added… Just I have no idea what they are for in the current example:
Hello @tmortagne I can’t check in our actual installs as we use XJetty now. However I didn’t make it up. I have used the setup that way during months, following this discussion:
Not saying you made this up (I’m even pretty sure it’s the right way to do this in some context). I’m mostly just agreeing with you that the documentation should not indicate a way to configure the memory as if it was the obvious way to do it when even in the case of Tomcat 9 it can vary a lot depending on the system.
There’s currently a lack of documentation about the readonly mode. It’s a quite a powerful feature implemented for more than 10 years. As of now, it seems like it’s a bit buggy and not deprecated. We’d need to discuss what to do with this feature before writing a doc, but it definitely should be documented. It would make it easier to maintain and use
Development Practices page could be split into multiple pages, as it contains information about project roles, JIRA issues and some license templates, which could all be in separate pages. Since some sections are only redirects to other pages, excluding some titles from the table of contents could help it feel less crowded (and reduce the 2 page table of contents to something more understandable).
The page feels bloated to me, like it tries to tackle too many subjects at once. I think an updated structure would help.
Also, adding the missing tracks in the Onboarding and reviewing the existing ones, as some links are broken/outdated. Maybe adding a more gradual presentation of XWiki concepts first, so the basic concepts are clearly presented, then the high level structure and data flow, then specifics for each subject.
I found inconsistent usage of some terms, such as Space and Page on the Nested Pages page, or XObject and XWiki Object. There should be only one way of refering to a concept.
The User Guide Track is a normal link (the first one on the page). This means it is easily skipped over, since it looks like a link to a wikipedia definition of wikis; Adding it as a big obvious ‘call to action’ button and making it clear that it is the intended way to proceed would solve this issue.
The image in the bottom part of the page is visible when first loading up the page, which can be distracting and lead to skipping the text in favor of reading the diagram.
.
