Perspective of OrchardCore from a new learner

[RemcoW2002]

Hi there, you've probably seen me open some discussions in the past two weeks. I've been trying to get into learning OrchardCore but have ran into multiple issues. I wanted to make this discussion not to just ask for help (though solutions are welcome!) but rather to give an idea of what it's like for someone completely new to OrchardCore.

I would like to stress that I am not greatly experienced when it comes to using a CMS or Razor, I have dabbed in a few things here and there but come mostly from Svelte(Kit), React, etc type of web development. If I at any moment make any remarks that are obvious, or seem to be passive aggressive, or rude, then please keep this in mind. I also don't intend to say that Orchard is bad or this like a thread to vent or let my frustrations out. I just hope that perhaps this perspective can help realize changes that can create a more easy and better learning experience for others in the future.

Anyways, after seeing this project has been worked on for years, I can imagine it can be hard to see what might be unclear to newcomers. So perhaps my perspective could help give a better idea of how to improve things and make the learning curve less steep. Here are some of the main issues I ran into:

1. Documentation feels incomplete and unstructured.
   Following the getting started guide works, but then what? There's no clear path forward. I tried making my own theme, but basic questions like "how do I access styling" or "what are the common conventions" aren't really answered. I guess I am missing that “Next →” button. Some sort of guidance of what is best to learn/dive into next to slowly but surely get a hang of orchard. Due to the current structure and way of trying to understand it by fiddling I’ve solved many things I had to come back to, because only later in the documentation would I see the right way of doing it.
   Additionally I often found myself on what is apparently the old documentation when searching for solutions, which just added to the confusion. Why are these older documentations even still a thing? Some examples are over 6-8 years old and clearly show old code, at least a warning at the top that this is no longer used would be nice.
2. Liquid vs Razor is confusing.
   While some parts have clear examples for both, others like the culture picker are only shown in Liquid. When you try to convert Liquid code to Razor, you often run into undocumented requirements or differences. For instance, image loading in Razor needs string casting that's never mentioned in the docs.
3. Outdated tutorials are misleading.
   The Dojo course series, while largely helpful and much appreciated, uses outdated methods and conventions (specifically from episode 28-30). Following it exactly (even with updated syntax (like the async changes for example) didn't work twice. Later I found you can just add widgets through admin - which was buried in the docs past the mention of the seemingly outdated tutorial series. Though creating your own widgets through code comes with one of the primary benefits that it is reusable in other projects, in other words you can easily take your own modules and thus parts and types into other projects. This is something I am of course still unable to do because of the above issues.
4. Basic functionality issues:
   • Live reload doesn't work for the navbar in Razor (works fine in Liquid), I get no errors I just have to rebuild the project each time for effects to take effect here.
   • Culture picker implementation is seemingly complex in Razor compared to Liquid, again I can't find any documentation about this despite there being info about it for liquid
   • Some features like localizing taxonomies/menu items are buggy, they don’t translate as other items do with the culture picker.
   • Common Razor alternatives to Liquid syntax (like await DisplayAsync(Model.Content)) are hard to find.
5. Though similar to the widgets problem, creating custom content is unclear. The documentation gives code snippets but doesn't explain where they go or how they connect. There's no structured explanation of creating a fully custom content type as a widget. Talking about this in particular: [Content Types - Orchard Core Documentation](https://docs.orchardcore.net/en/latest/reference/modules/ContentTypes/). I understand there is a video series that explains it but from my personal view I would much rather have the documentation be a longer extended more detailed explanation and have the video as a helpful guide, also because docs are of course a lot easier to maintain as well.
6. Why is liquid even used exactly? Not a critique, but to me using Razor seems like a better choice, from what I can tell many people use razor rather than liquid, so why liquid?

I get that some of this might be due to my inexperience with CMSs and .NET/Razor in general. But the lack of current tutorials, clear documentation paths, and community resources makes the learning curve way steeper than it needs to be in my opinion. Simple issues take way too long to solve because solutions either don't exist online or are outdated.

Again, this is meant as constructive feedback. All of my issues are likely or at least partly due to my inexperience, though yet again I feel like it's also part the lack of structured documentation - OrchardCore seems powerful, but getting started with it is tougher than it needs to be. Would love to hear thoughts on this!

[Piedone]

Thank you for sharing your thoughts. Would you like to join the Tuesday meeting so we can talk about your experiences in a more fluid manner?

Just replying to what's quick and straightforward. Just as you didn't mean the above in a confronting way, please don't take this as a lecture either.

1. Very good point about the path forward. As for the "old documentation", I guess you refer to the Orchard 1 docs. Those are kept not to destroy resources for the legacy CMS (which is still running thousands of sites).
2. If you found such concrete errors or omissions in the docs, please contribute the fixes. See https://docs.orchardcore.net/en/latest/contributing/contributing-documentation/.
3. I recommend you use the OC source, cloned to your device, as well as Lombiq OSOCE (and especially the Training Demo) as a living reference. These contain a huge number of examples of anything in OC. These are the widgets types created from migrations built into OC (understandably though, you wouldn't know what exactly to search for), and here are some from Helpful Extensions. The Code Generation Helpful Extensions feature can even generate the migration code for your content types (widgets) created from the admin. (And Shape Tracing will answer questions you may have about shapes.)
4. For concrete suggestions, it would also be great if you could open issues, especially if you found the solution (or just contribute those directly).
5. See the previously mentioned Training Demo, that has a guided example of creating content types (and content parts, as well as content fields) from code (and also about how to manage content items from code otherwise).
6. Razor is for developers who are comfortable with C#, writing code during local development. Liquid is for frontend developers who only work with client-side technologies, as well as for creating templates right there on the admin. It's also safe (unlike Razor), so you can allow people to use it for customization even in a public SaaS. Furthermore, it's used for templated text (like to generate the content of the <title> tag) in various settings.

[RemcoW2002]

Thank you so much for taking your time to give this detailed response.

1. I figured that's what it was for, perhaps still some message somewhere at the top or like a pop-up for those that are new to notify them that this is for the legacy CMS, I saw on some pages there was an archive notification but not on all.

2. I will try to do this in the future, though I am admittedly still quite hesitant, especially from what you've mentioned in your response I am clearly not super knowledgeable about OrchardCore and wouldn't want to waste people's time opening issues or making contributions that are nonsense.

3. Thank you so much for all these resources, I will make sure to check them out!

4. Same as mentioned above, though I do keep track in a large document for myself what my current solutions have been, once I am more confident it's the correct solution I will open some contributions. (Again, I've already had to change my own solutions due to them being inefficient or simply not the way its meant to be done, hence why I am still a bit hesitant to go out and suggest all of those things right now but they will come)

5. Again, thank you.

6. Also clear now.

Again thanks a lot for taking your time to respond in such a detailed manner, it's genuinely much appreciated and makes it so much more welcome and exciting to continue learning this!

Edit: Just saw the invitation for the Tuesday meeting, sadly I am pretty much never available that day around those times.

[Piedone]

I'm happy to hear that, and thank you for being constructive!

1. I've opened an issue about making the docs more apparent: Display banner on every documentation page that it's for O1 OrchardDoc#367.
2. and 4. Don't worry, we'll try to be helpful and I'm sure we won't be rude :). Recently, there have been quite a few docs contributions by (relative) newcomers too (e.g. Update Documentation for Display Mode shape type #17389, Added documentation for fields with alternate display modes. #17333, Update Docs Taxonomy #17213); even small clarifications, and especially fixing downright errors, help a lot.