Document best development practices for editors (format: improve your integration in X days)

[GauBen]

Integrators are in charge of creating a good editor experience but this isn't always easy. Many things, at each development step, can be done to improve EX (editor experience) and if we don't document them, they cannot be guessed.

The goal of this task is to collect good practices and write a sharable document.

-> https://github.com/Jahia/gautier-braindump/blob/main/articles/integration-best-practices/README.md

-> https://github.com/Jahia/gautier-braindump/issues/19

Additional resources:

• PS checklist https://docs.google.com/spreadsheets/d/1HRRbR86phuyyq4dj0K6BKZSFiIVOBgGXhF4JKddfjNU/edit?gid=0#gid=0

---

Feedback

préciser qu'il s'agit des pages créées par les utilisateurs

catégorie -> hiérarchie

liens *internes
cta as child but points to something as weakref

si vous voulez ajouter des courtes descriptions, feel free https://docs.google.com/spreadsheets/d/1YwQ97cCZ2FYDpcSuOm2S0sM57R3EHQyBjep7bRZotE0/edit?gid=0#gid=0
Le plus important serait imho de distinguer quels mixins sont utiles / accessibles aux intégrateurs (certains je pense nous sont réservés, j'ai bêtement recensé tous ceux que j'ai trouvés). si qqun a le courage et la connaissance de virer ou mettre en rouge par exemple tous ceux qu'on ne doit PAS documenter, ce serait super (edited)

• "On most projects, the visitor experience is specified and the authoring experience isnt"

• Make prerequisites explicit

  • Ensure bandwidth for business teamduring theg project
  • Know Jahia
    • Business team should have a light trainng half a day and each should have created a landing page
    • All developers should be trained
    • One experienced developer
    • Understand what is a web page, a template, a content type, a main resource (full page content)

• Specifications

  • Ensure that the design is really meant to be used on an enterprise website, with reusable components /  Many projects inherit mockups that are not consistent and not compatible with content management at scale

• Integrating

  • Let's explicitely state: Most projects require 1 to 4 templates and 4 to 10 content types with different views.
  • Goal = ease maintenance, ease editor's life

• Sectioning components & page templates

  • By default, the usual recommendation is:
    • Free page template + section component + content templates
  • Exceptions do apply, you may need a dedicated template for
  • List lexical options for sections: slices, blocks, ..

• Categories => hierarchies / collections

• h2: managing content relationships

• How to relate content => weakreferences vs children

• Call to Action is used for both children and weakref

• Specify for inheritance : "inherit primary node type"

• Page Model ?

• jmix:mainResource improve explanations

• Need "fil rouge" for semantic types and layouts

• "Dont force a structure on editors" => Wrong title ?

  • Also, team is not fully convinced

• Components categories

  • Other splits: "compose your page" vs "business content" / semantic / domain

• Top 3 of worst ideas that will

  • Reinvent caching
  • Reinvent the UI
  • Reinvent the search

• in caching

  • missing "and render this weakref" from your view
  • addcacheDependency should be mention. vs render weakref

• visibleInContentTree

  • Add screenshot

• Ask damien where the "visual out of context" is used

• Missing recommendations on in context helper

  • this content can be edited here

• page folders => menu items

• page models => not in import.xml

• create an issue to create an alias for jmix:contributeMode . contributeMode should NOT be used. Will be refined with GOAT.

• as a rule of thumb, a complex project may used between 3 and 6 modules. Use lifecyle as a criteria.

• missing : cfg vs site property

• digg into "declare properties that should be indexed for search"

• plan for scalability for content folders (subfolders by year)

My 2 cts à propos de la derniere partie
Unless the module has a very clear puprose and could be reused in multiple projects / platforms (example : a connector to a specific saas or internal system) - as a rule of thumb, a typical project may used between 3 and 6 modules. Use lifecyle as a criteria.

et il faut une section sur la customization des UI (en vue de simplifier) aka les json overrides

Et on a oublié primary :)