[DOCU-1629] Trim the "Configuring a custom bundle" tutorial to focus on version handlers Created: 19/Jul/18  Updated: 06/Sep/19

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

Type: Task Priority: Neutral
Reporter: Christopher Zimmermann Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: maintenance, tutorial
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
relation
is related to DOCU-1712 Rewrite "Creating a custom bundle" tu... Closed
Template:
Acceptance criteria:
Empty
Task DoR:
Empty
Date of First Response:
Epic Link: Pre-2019 mgnl-staff requests

 Description   

I think we should rename the “Configuring a custom bundle” page. For example to:  “Managing configuration with Version handlers and update tasks”

https://documentation.magnolia-cms.com/display/DOCS57/Configuring+a+custom+bundle

 

I think it would be helpful to split the tutorial, or remove some information of the tutorial to another document. This would make the tutorial shorter and more focussed on one topic, the version handler.

Most important to remove:

The intro of "Convert your project module into a Magnolia module."

Create a module descriptor

(They are not that relevant to the new topic focus - and therefore add weight and complexity)

 

Possibly also remove:

"Terminology: module" box.

(Not that relevant)

"Adding fs-browser-app"

The tutorial is now about the version handlers - we could just give them a starter bundle with the fs-browser-app already in it. It would make the tutorials more independent. It would make the tutorial shorter and less complex.

(The information of how to add modules to a bundle is already covered in: "Creating a custom bundle" https://documentation.magnolia-cms.com/display/DOCS57/Creating+a+custom+bundle)

 

Using the removed content

I could see a new tutorial "Create a magnolia maven module" or "Create a Magnolia Java-based module". Which could include some or all of this content.

Currently in the documentation I only see this section on the "Module Structure" page. 

https://documentation.magnolia-cms.com/display/DOCS57/Module+structure#Modulestructure-CreatingaMagnoliaMavenmodulewithMavenarchetypes

This topic would deserve a page or tutorial of its own.

 

 

 

 

 

 



 Comments   
Comment by Christoph Meier [ 18/Jan/19 ]

I have (nearly) finished the overhaul of the tutorial Creating a custom webapp with Maven (DOCU-1712). 

New version: https://documentation.magnolia-cms.com/display/DOCS60/Creating+a+custom+webapp+with+Maven

The new version is replacing the https://documentation.magnolia-cms.com/display/DOCS60/Creating+a+custom+bundle - which I will delete, as soon as the new one is public.


Once when the new version is public, I propose to hide (send to cemetery) the "related" tutorial https://documentation.magnolia-cms.com/display/DOCS60/Configuring+a+custom+bundle . That one is ("Configuring a ...") is a follow up / it is kind of the "Part  II" of the earlier https://documentation.magnolia-cms.com/display/DOCS60/Creating+a+custom+bundle 

 

Comment by Christopher Zimmermann [ 21/Jan/19 ]

In this context it is worth to mention, that we also have a ticket to refine (and split!) the Configuring a custom bundle tutorial, see DOCU-1629.

That comment references this ticket - is that a typo - is there a nother ticket?

Will the version handlers and install tasks still be documented somewhere?

 

Comment by Christoph Meier [ 22/Jan/19 ]

czimmermann - My above comment is actually on the wrong ticket.
(But 1st I wanted it ti add where it belongs, at DOCU-1712, plus here too. So, yes, it is a bit confusing  ... sorry!

Rewriting the tutorial Creating a custom webapp with Maven (DOCU-1712) is nearly finished.

Will the version handlers and install tasks still be documented somewhere?

Yes. In the context of >>this<< ticket (DOCU-1629), replacing the page Configuring a custom bundle.

I have changed the above comment a bit.

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