[DOCU-896] Refine YAML page Created: 02/Dec/16  Updated: 03/Jul/17  Resolved: 24/May/17

Status: Closed
Project: Documentation
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Neutral
Reporter: Christoph Meier Assignee: Martin Drápela
Resolution: Done Votes: 0
Labels: core
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
relation
is related to DOCU-1016 Reflect "JCR Export improvements" Closed
Template:
Acceptance criteria:
Empty
Task DoR:
Empty
Date of First Response:
Sprint: Docu Sprint 25
Story Points: 8

 Description   

2 major aims

Mention YAML as bootstrap format
Since YAML with "Provide JCR bootstraps as YAML (too)" - YAML no longer limited to use for definition items only. This must be reflected on the YAML page.
E.g. adapt the section "YAML in the context of Magnolia"

Add more sophisticated examples ...
.. for YAML as item definition language.

The page just covers the very basic.
Let's add a few more sophisticated things, such as:

  • Reusing existing maps when defining a new one using >>
    • here we may also mention the down sides which may appear when decorating
  • etc. pp

Check links, etc.



 Comments   
Comment by Christopher Zimmermann [ 23/May/17 ]

I would recommend that the YAML page itself becomes very slim: an overview of the format and mention the two ways it can be used in Magnolia. The bulk of the actual usage I would move to pages about the respective features. And maybe a few words about the benefits of YAML as a file format (1. Great diffs & merging due to the strict spaces policy. 2. Great for text because quotes and other special characters dont have to be escaped as in JSON and XML.)

I recommend this because "YAML" is not an actual feature - its simply the file format we have decided upon for our features (1. config by file. AND 2. export/import content)

I think this change is important because people should be less focussed on "YAML files", they need to understand the concepts of "Definition files" and "Bootstrap files" regardless of format. Without this shift there is more likelyhood for confusion about how "YAML files" behave differently in different contexts. - this is related to the action name change from "Download YAML" to "Download definition".
I'm available to discuss!

Comment by Martin Drápela [ 24/May/17 ]

Initially, the page update was done on the live page, but a more drastic refinement was applied to a new copy of the current page:
https://documentation.magnolia-cms.com/display/DOCS/YAML+v2
where the intro to YAML syntax was removed in favor of the YAML resource links at the end.

Comment by Christoph Meier [ 25/May/17 ]

Well ...
... if i am not completely wrong, somebody from PM was asking to add more advanced features such as "reusing" a a map in map.
Maybe it was ahietala?
So ... should we add more sophisticated examples of using YAML (in the context of an item definition)?
example:

main:
    availableComponents: # using all components from footer plus others
      <<: *footerAvailableComponents
      html:
        id: mtk:components/html
      linkList:
        id: mtk:components/linkList
      teaser:
        id: mtk:components/teaser
      video:
        id: mtk:components/video

(snippet from https://goo.gl/oQjlB6)

I agree that we could remove for instance the section "YAML data is transformed to definition classes".
This could be explained somewhere else or just skipped.

Comment by Martin Drápela [ 25/May/17 ]

The reusing was already mentioned as a separate subsection called "Reusing the existing definition".

Comment by Martin Drápela [ 25/May/17 ]

We could also add the "Reusing a mapping" section to https://documentation.magnolia-cms.com/display/DOCS/Reusing+configuration
(at the place of the hide block)

Generated at Mon Feb 12 01:13:19 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.