|
| Summary: |
Improve the names and descriptions of the Async and Cache macros and of their parameters |
| Issue Type: |
 Improvement |
| Affects Versions: |
17.10.14, 18.8.0 |
| Assignee: |
Unassigned |
| Components: |
Rendering - Async, Rendering - Cache Macro |
| Created: |
22/Oct/26 11:58 |
| Priority: |
 Major |
| Reporter: |
Charpentier Lucas |
| Description: |
The names and descriptions of the Async and Cache macros, and of their id parameters, repeat the macro names and use developer terms, so a user cannot tell what the reader gets or what the id is for. The macros to change, with the file where most of the fix is done:
KOs covered
| Macro |
Criterion |
Parameters |
Problem |
| async |
D1 wording |
|
"Async macro" is a developer term, and it names only one of the two things the macro does, the other one being the cache of the result; the documentation lists it under the developer macros, but the macro is in the user category Content, so it is meant for every user. The cache macro, which is in Development, shows that users who know the technology look for it there. |
| async |
D2 summary |
|
The description "Execute asynchronously and/or cache the macro content." repeats the name, "asynchronously", and uses the same jargon; it adds only the cache and does not say what the reader gets, the page showing at once and the slow content replacing a placeholder when it is ready. |
| async |
D3 category |
|
The macro is in Content, like content, include and display, which fits a macro that wraps wiki content. The compared macros are in different categories, content in Content and html in Development, so the measure gives no single category. Users who look for what the macro is used for, slow scripts, find velocity, groovy, html and the cache macro in Development, and the macro is not listed there. |
| async |
C1 clarity |
id |
"Identifier" with "The identifier associated with the content. If left empty it's deduced from the macro location." says it is deduced when empty, which is enough for a technical hook, but not that it is the key of the cached result, so only useful with cached="true", nor that several can be given. The French name, "Ecraser l'identifiant", and the German one, "ID überschreiben", say "override", unlike the English one. |
| cache |
D2 summary |
|
The description "Caches content." repeats the name and adds nothing: it does not say that the result of executing the content is kept for a time and then computed again, nor that the scripts of the content run only once, which is the main limit the documentation gives. A simple wrapper that repeats its name is still a KO. |
| cache |
C1 clarity |
id |
"Id" with "A unique id under which the content is cached." says what the value is, which is enough for a developer hook. It does not say that an empty id uses the content itself as the key, which the documentation does and the documentation also warns that the content does not guarantee unicity. In French and German the name is the ID in English too. |
Impact found on macro fluidity These 6 KOs come from the WYSIWYG usability audit of the macros, under the criteria C1 clarity, D1 wording, D2 summary, D3 category of its usability criteria. The page of each macro, linked in the table, has the full notes and the steps to reproduce. Fixing them means changing the translations of the macros and, for a name or a category, their definitions. |
|
