Published
Wiki source code of Fix the XWiki Instance Sizing page and link it from the Installation topic
Last modified by Eleni Cojocariu on 2026/08/18 10:34
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | Review of [[XWiki Instance Sizing>>doc:documentation.xs.admin.installation.xwiki-instance-sizing.WebHome]] against the Documentation Guide, the XWiki sources and the legacy [[Performance>>doc:Documentation.AdminGuide.Performances.WebHome]] page it supersedes, plus the two neighbouring pages that should have been sending readers to it. |
| 2 | |||
| 3 | **The page was typed as a How-to.** It is stored as ##type=howto##, but its title is a noun phrase and its body is five tables with no procedure, so the Documentation application renders it under an auto-generated **"Steps"** heading containing no step. It becomes a **Reference** — the type defined as covering a topic extensively and preferring tables. The title, the page name and ##target=administrator## all stay valid, so nothing is renamed and no backlink has to be repointed. | ||
| 4 | |||
| 5 | **Things that were wrong:** | ||
| 6 | |||
| |
7.2 | 7 | * The number of documents was to be read "from the Administration panel under //Diagnostics//". **XWiki has no Diagnostics administration section** — no ##admin.*## key in any ##ApplicationResources.properties## of ##xwiki-platform-core## declares one. It now points at the "Index" tab of the [[Page Index>>doc:documentation.xs.user.base.page.view-index.WebHome]], and says plainly that counting versions takes a database query. |
| |
1.1 | 8 | * Both of the page's own section headings were **level 1**, i.e. siblings of the structure headings the application generates, so they escaped the section meant to contain them. They are level 2 now, and "Instance Sizing" — which repeated the page title — becomes "Sizing Recommendations". |
| 9 | * The Tiny and Small rows of the page-views dimension both claimed 0.5. All three dimensions are now expressed as upper bounds, which cannot overlap. | ||
| 10 | * The Clustering link used the reference without ##.WebHome##, which resolves only through a 302 to the nested page — the page's own Related field already links that page directly. Plus a space before a colon and two double spaces. | ||
| 11 | |||
| 12 | **Eight tables became two.** The three dimension tables shared the same five profile rows and the five per-profile tables shared the same four resource rows, so the one operation the page asks for — take the highest profile of the three dimensions — meant reading three tables, and two profiles could not be compared at all. There is now one profile table and one recommendation table, both 5 by 5. The five per-profile headings and their "Suitable for …" sentences became a "Typical deployment" column, the worked example lost its heading and eight of its nine lines, and the manual table-of-contents macro is gone. **No number changed**: the thresholds, RAM, heap, CPU, storage and the Huge-scale cluster sizing are carried over as they were. | ||
| 13 | |||
| 14 | **Two facts were missing.** The page recommends a JVM heap without saying where a heap is set — now a FAQ entry linking [[Java Memory for Tomcat>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.java-memory.WebHome]] — and it dropped the two qualifications the legacy Performance page attaches to exactly these numbers: over-allocating the heap costs performance through longer full garbage collections, and HSQLDB keeps the whole database in the heap. The HSQLDB sentence links [[HSQLDB Limitations>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.install-relational-database.configure-hsqldb.hsqldb-limitations.WebHome]], which is where that fact lives, rather than restating it. The FAQ field was empty and now holds those two questions, the first of them absorbing an information box removed from the body. | ||
| 15 | |||
| 16 | **Two neighbouring pages could not reach it:** | ||
| 17 | |||
| 18 | * the [[Installation>>doc:documentation.xs.admin.installation.WebHome]] hub highlighted five of its six children and omitted this one, so it never linked a page it introduces. The sixth entry goes in the position the navigation tree's pin already gives it, second, after Prerequisites; | ||
| 19 | * [[Prerequisites>>doc:documentation.xs.admin.installation.prerequisites.WebHome]] still sent its two hardware bullets to two sections of the legacy Performance page, although its own Related field already links this one — and the anchor parameter of both links is **not rendered** by xwiki.org, so all three hrefs on that page land at the top of a 24 kB legacy page. They become one bullet pointing here. | ||
| 20 | |||
| 21 | **Deliberately left alone:** the warning banner, which is what makes the numbers honest; the title and page name, which the Reference rules already fit; the empty Technical ID (installation pages carry no extension) and empty Highlights (a leaf page); the legacy links to Performance and Clustering, which have no page in the new tree yet; and the sizing figures themselves, which are the author's domain judgement. No screenshot was added: this is a two-table Reference, and the only UI it points at is documented with screenshots on its own page. | ||
| 22 | |||
| 23 | **Follow-ups, not in this change:** in the Docker row of Prerequisites, the "Persistent storage configured" link has no target at all — only an anchor, which is not rendered — and converting the legacy Performance page, whose remaining sizing-adjacent material (xwiki.org's own ##CATALINA_OPTS##, the XWiki SAS cloud configuration, the implicit All Group setting, database indexes) belongs to that conversion rather than here. |
