O1 docs and OrchardCore docs

[planetClaire]

On googling OrchardCore questions I keep landing on the O1 docs which often help with my question, but also often lead to confusion, since it's not that obvious at first that they belong to the legacy Orchard. For example today I googled "orchard assets gulp" and landed on https://docs.orchardcore.net/projects/O1/en/latest/Documentation/Processing-client-side-assets/ - this article helped a lot and seems relevant to OrchardCore, so, a couple of things:

1. For a newcomer, can we make it more obvious that the O1 docs are for O1, with some kind of banner/alert explanation and link to the new docs? https://docs.orchardcore.net/en/dev/ at the top of every page?

2. The "processing clientside assets" page referenced above could probably be adapted quite easily for OrchardCore? I can't find anything on the new docs except for a section in each of the built in themes, eg: https://docs.orchardcore.net/en/dev/OrchardCore.Themes/TheComingSoonTheme/#advanced-usage (actually I think this might be out of date re tasks) which isn't really aimed at module development, so I think this page would be a great addition.

[deanmarcussen]

Generally agree in concept, though the processing client side assets is a bit outdated, as we don't ship a gulp file through nuget, nor would the gulpfile we use to build assets quite work if you copy it directly to a nuget based projects (there's a couple of folders, i.e. Themes & Modules that it globs, and has to be changed to glob your own theme and module folders.

Plus some other tasks which are specific to the OrchardCore build pipeline.

We haven't really any specific docs for Orchard Core, or suggested best practise. Some people are using gulp (I think @Piedone might have done some helpers / docs? ) Others have moved onto webpack for theme development, but then you still need a gulp task runner, if you're building modules as well, to build the webpacks...

Can get tricky :)

However one thing I would say, is there is quite a lot of documentation that is really relevant, and could come over.

Permissions for example is well documented for O1, gets many questions on gitter, and is very similar in concept to O1

Banner for the O1 docs sounds like a good idea, that has caught plenty of new users out.

[planetClaire]

I'd forgotten about development with the Nuget packages, which seems to be the preferred method - the gulp file isn't relevant, which I guess is a good thing as it encourages us to use our preferred approach for assets. I'm still working in old O1 projects and use webpack with npm as a task runner rather than gulp & prefer that method, I never liked the way new themes/modules were generated with Assets.json and all that, and I see now that's no longer a thing...

Still, I needed this info for a little script change I wanted to contribute to a core module. First place I looked was the docs and found nothing, so I googled it, and ended up on the O1 docs as happens a lot. This discussion would be great in the docs :) Maybe a Contributors Guide, and something on Approaches to asset management in Module & Theme development.

[Piedone]

Yeah, we've created NPM MSBuild Targets for easy build-integrated NPM installation and Node tasks, as well as Gulp Extensions with some goodies for gulp specifically. I don't think there's too much that Orchard could provide on this end (that assets pipeline can't be used from NuGet) so you can use something like this.

As for the banner, @agriffard any simple MkDocs thingie for this?

Would you like to document some of your findings @planetClaire? :) Here's the contrib guide.

[planetClaire]

Will give it a go 👍

[Piedone]

Thank you! Let us know here if you need pointers.