[DOCU-1676] Rewrite "My first content app" tutorial Created: 31/Aug/18  Updated: 23/Nov/18  Resolved: 12/Oct/18

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

Type: Story Priority: Major
Reporter: Christoph Meier Assignee: Martin Drápela
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
causality
dependency
is depended upon by DOCU-1707 Rewrite "My first translation" tutorial Closed
is depended upon by DOCU-1710 Rewrite "Accessing content on the cli... Closed
is depended upon by DOCU-1711 Rewrite "Creating a website with Magn... Closed
duplicate
duplicates DOCU-1004 Rewrite "My 1st content app" - focus ... Closed
Template:
Acceptance criteria:
Empty
Date of First Response:
Epic Link: UI-framework-6.0-developer-preview
Sprint: Docu Sprint 59, Docu Sprint 60, Docu Sprint 61, Docu Sprint 62, Docu Sprint 63
Story Points: 13

 Description   

Rewrite the tutorial "My first content app".

Compared to the old version - which is done with a Magnolia Maven module, the new tutorial will be rather different. Here are some key points of the new approach:

  • All is done within a light module.
  • The "basic" version must utilize a Content type definition
    • e.g. reuse the app tourGuides-app.
  • An extended version maybe could be done without a Content type definition (not sure about this) ...
  • We could reuse sample code which is already used for the Content type docs (Add link here to the final destination of these examples)
    However - the CT sample code light module contains already 4 CTs and 4 apps.
    For this tutorial it could be more meaningful to have something distinct which resides in its own light module.
    But the existing examples can be used for inspiration.
    ¯_(ツ)_/¯

 This app as shown in this tutorial will be the base for some other tutorials, which must be rewritten, and which earlier have been relying on the old version of the "My first content app". That's why this story has a high prio.



 Comments   
Comment by Christoph Meier [ 03/Sep/18 ]

mdrapela

Currently the examples used among Content types (CT) ref. pages are there:
=> https://git.magnolia-cms.com/users/cmeier/repos/content-type-examples 
But later on this code will be moved to another repo (ui, or content-types).

The repo content-type-examples contains 4 content type definition, and for all of them there is an app definition too.

 

Comment by Julie Legendre [ 16/Oct/18 ]

JL review paused. My main concern is the structure: for a beginner's tutorial, i find there is a too much reading to do before actually doing something. Commented with suggestions on the tutorial pages. Will pick up the review if / when the structure is changed.

Comment by Christoph Meier [ 24/Oct/18 ]

I have read again the tutorial and also have tried it out following the instructions.

I have added a few inline comments, but these are basically minor things.

I like it!  I would consider it a good and useful tutorial.
Now it imho has the right balance of explaining the basics and hiding details (which can be figured out following links.)
¯_(ツ)_/¯

When it comes to tailoring the app: A few things could have been done on the CT def. instead of doing it in the app descriptor. However, the focus here is the app, thus fine.

One remark concerning the provided content:
My-Good-Reads/
├── Sci-Fi
└── Science
Not sure whether we "need" the "super-parent" folder "My-Good-Reads". arguable.
For me the given workspace is the my good reads workspace. Hence no need for that extra folder. I would rather remove it. But if you have a good reason to keep it ...

Thinking about reusing the outcome of this example which may become the base for other tutorials (as mentioned in the description of the ticket):
It should be a good base.
In this context: probably easier when we can get rid of the folder "My-Good-Reads".
In some of the tutorial (in which I wanted it to reuse) - I may "extend" the app adding an image property linking to assets. (But having no assets in the tutorial - I guess that's fine).

Comment by Christoph Meier [ 25/Oct/18 ]

Concerning the content structure. Have a look at the assets app.

There we have something like:
/tours
/travel-demo
/tour-types
/...etc

It is not starting with:
my-fine-assets/
├─ tours
├─ travel-demo

Every JCR workspace has indeed a root node - it is just never displayed.

Data wise I see no good reason to have the My-Good-Reads

But fine. Let's see what Julie means.

Comment by Julie Legendre [ 31/Oct/18 ]

Language review done. A few outstanding comments in the pages (mdrapela). I "unhid" some of the explanation expandables. I think they are essential for the user to understand the tutorial.

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