[DOCU-774] Evaluate solutions for a distinct docs section for front-end developers Created: 18/Jul/16  Updated: 03/Jul/17  Resolved: 04/Oct/16

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

Type: Task Priority: Neutral
Reporter: Christoph Meier Assignee: Julie Legendre
Resolution: Done Votes: 0
Labels: core
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
dependency
is depended upon by DOCU-772 Frontend developer 'Landing page' Closed
Template:
Acceptance criteria:
Empty
Task DoR:
Empty
Date of First Response:
Sprint: Docu Sprint 13

 Description   

Tasks:


Label pages on DOCS which are relevant for frontend developers.
Use the label front-end development
See https://documentation.magnolia-cms.com/display/DOCS/Front-end+development+related+pages+-+aggregated+list



 Comments   
Comment by Christoph Meier [ 19/Jul/16 ]

I was labeling pages with the tag front-end-development. These pages are in a narrow or broad context relevant for front-end developers imho.
Some "decisions" - whether a page was labeled or not - may be arbitrary.

See https://documentation.magnolia-cms.com/display/DOCS/Front-end+development+related+pages+-+aggregated+list

Most these pages are also relevant for "other Magnolia developers" - those guys which are not typical front-end developers but which are using Magnolia since centuries.

Comment by Christoph Meier [ 19/Jul/16 ]

Thoughts about a dedicated docs section for front-end-developers

How to separate the groups?

If we separate between front-end-developers and others. What type of devs are the others? Back-end developers? What about full-stack devs?
If we have one distinct section for front-end-developers, how many other section would we have? Or would there be one section especially for front-end-developers and one section "for all"?

How to handle the distinction technically?

Since many pages are valid for "both" groups - we would had to reuse content - for which confluence is not very handy. How to handle this?

Should a "distinct section" be a separate wiki space?
What about having just 2 nav-trees in the same space?
What about having just a dedicated top-level page on the space aggregating content or at least links for the front-end devs?

Comment by Antti Hietala [ 19/Jul/16 ]

If we separate between front-end-developers and others.

Think of this effort simply as a campaign aimed at front-end developers. Collect a few resources that make a front-ender's life easier and present them in one place. That's enough. Don't worry about creating equally effective campaigns for back-end developers. We are making a big push about front-end dev so that's your audience for now.

What about having just a dedicated top-level page on the space aggregating content or at least links for the front-end devs?

This is my preferred option. It doesn't involve restructuring, building artificial doc page hierarchies or splitting topics. If a topic is relevant for a front-ender then label it and have the aggregation page do the work.

Comment by Martin DrĂ¡pela [ 05/Aug/16 ]

I'm far from being able to do a QA for such a complicated issue. Rather, let me also add a suggestion, hopefully a workable one.

As I see it, having some doc pages already labeled with the front-end-development label should make it relatively easy to "background" everything else. Let's then make a full use of this attribute. The server, of course, will have to know somehow that it is a front-ender who is staring at the screen now. This could be checked - for logged in users - via the <meta name="ajs-current-user-fullname"> tag.

If the ajs-current-user-fullname would be associated with a "frontender" property (in MagDAP, or elswhere), the server pushing the DOC content would grey-out the links and page content not associated with the front-end-development label.

Doc hyperlinks to pages labeled with the front-end-development label would be rendered in the usual magnolia green, but hyperlinks to non-front-end-development pages could be CSSed as #FF0000, suggesting that the target page has a wider scope.

Creating two nav trees or another distinct section for front-enders is certainly possible as well, but IMHO much more complicated than personalizing Magnolia DOCs to frontenders via the already existing front-end-development label.

Comment by Martin DrĂ¡pela [ 12/Aug/16 ]

Following the discussion, it turns out that p13n-ing the content for frontenders who are logged in is not a very viable option: a vast community of (unregistered) frontenders would be simply eliminated from accessing the p13n-ed content for frontenders.

So, while paragraphs 3 and 4 of my previous post still hold, I suggest mirroring the whole /DOCS/ space to a new /FEDOCS/ space, which however - being a mirrored space - would never be edited directly.

Comment by Julie Legendre [ 04/Oct/16 ]

DOCU-772 published
DOCU-807 won't be started until after 55/mnow
Can we close this story cmeier? I think the getting started guide described in DOCU-807 is a first solution for this ticket.

Comment by Christoph Meier [ 04/Oct/16 ]

I agree jlegendre, for the time being i close this one.
R.i.p. dear DOCU-774 :-p

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