[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: |
|
||||||||
| 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 Add more sophisticated examples ... The page just covers the very basic.
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". |
| 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: |
| Comment by Christoph Meier [ 25/May/17 ] |
|
Well ...
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". |
| 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 |