The “Templating Tutorial” got merged into the older already existing repository for the marker based tutorials which are still available in the older branches.
They cover very similar topics - templating in TYPO3 with FLUIDTEMPLATE. Very roughly, I would say the “Sitepackage” covers the TYPO3 best practice way using a Sitepackage. The “Templating tutorial” has examples with templates in fileadmin (which is actually no longer considered best practice).
On the pro side of the “Templating Tutorial” I find it an easier read. It simplifies things in a nice way, while the “Sitepackage Tutorial” felt a little overwhelming.
If we look at the defintion of Tutorials (e.g in a text by Daniele Procida) they are “learning oriented” and must not necessarily follow best practices by the letter. But putting templates in fileadmin just feels wrong to me (actually I never really understood why this was done in the first place, why in this directory).
Opinions about this?
My goal is to make a decision: Do we need and want 2 tutorials? How do we describe them on the “Tutorials and Guides” page? Can we seamlessly walk a beginner through the wild and wonderful world of TYPO3?
Without judging which of the two tutorials you pointed out is a better tutorial for new users, I express my view about having more than one tutorial in general.
As with other systems, in many cases there is more than just one way to achieve something in TYPO3.
Offering two different tutorials for the same goal should not be a problem, as long as:
they don’t contradict each other,
both options are valid and officially “supported” (*),
both are kept up-to-date (**).
*) Storing system-related files under “fileadmin/” could be a reason to mark the document appropriately as “fileadmin/” is reserved for the user space.
**) Given the challenge of lack of (wo)manpower, maintaining two documents could also be an issue.
It also makes sense to refer to each other. For example a clear statement in the introduction section of each tutorial that highlights “This tutorial aims to achieve X by doing Y, but it does not do Z. If you want to achieve Z, please refer to document ABC.”
Both are great and helpful! Good points from @mschams.
In my opinion, if there are 2 tutorials for similar topics and in these case as they are on docs. they are “official” it needs a bit of framing. Using /fileadmin is not best practice, but it is ok to learn Fluid template basics. Around where the files are first created in the tutorial https://docs.typo3.org/m/typo3/tutorial-templating/master/en-us/MinimalDesign/Index.html#the-typo3-fluid-version that should be mentioned IMHO.
When linking them it would be helpful to advertise them as e.g. “starter” and “in-depth” and also cross-reference between them.
Besides the official TYPO3 “documentation word” there will alway be a - hopefully wide - spectrum of blog posts dealing with special aspects, providing tutorials and so on. We should encourage people to do so as much as we can. Maybe we can convince one or another of those writers from time to time to contribute their work to the official TYPO3 documentation. But usually that’s still a lot of work and therefore rarely happens.
On the other hand: Personally I definitely want to bookmark those articles and study them when I need to.
But why should I take those notes only for myself? So I once started with the “Tell me something about X” manual, which can mostly be conceived as an annotated link list. So: “Tell me something about templating” would be the correct rubrik here. If that existed (I haven’t checked right now) and contained the mentioned links - that would be a great help for me.
Take the “Tell me something about X” just as a first version of something I want to propose. It’s just an experiment addressing the question: How can we provide good links about TYPO3 topics.
As I’m writing this now: Perhaps we should offer and maintain a Github repository with curated link lists?
In my opinion people (even beginners) should be encoraged to not use “fileadmin” any longer (not for html templates but also not for the other configuration stuff). In best case they put everything into an custom extension (e.g. db stored typscript templates should be as small as possible). Perhaps the tutorial could be extended with a good practise examples for a folder strcuture like this (perhaps reduced):