search

AlchemyCMS / alchemy-guides

📜️ Source of the AlchemyCMS guidelines
https://guides.alchemy-cms.com
19 stars 46 forks source link

Chiperific additions #180

Closed chiperific closed 1 year ago

chiperific commented 1 year ago

As I'm building my first Alchemy app, I am adding my own lessons learned to the guides.

NOTE: the guides do not say anything about the depreciation of Essence#{Type} in favor of Ingredients (as a v6 upgrade?).

I'd be willing to help generate an "Ingredients-compatible" set of guides separate from this (as a separate branch?) so there aren't so many warnings in the guides (as there are now for v4 and v4.4 changes). I don't think it's a good idea to have the v4, v4.4, v5 and v6 discrepancies in one guide.

chiperific commented 1 year ago

@tvdeyen, is there any interest in looking at this PR?

tvdeyen commented 1 year ago

there is. thanks. but this takes time. all of this makes sense, but I think some of these things are user related. yet, the guides are developer focused. also, we need some kind of versioning. since we are on an old Vuepress version it might make sense to rewrite the guides in an more recent version or another tool that supports versioning.

chiperific commented 1 year ago

you pick a tool and I'll happily help contribute!

As to developer vs. user, the developer is the first user. As they build out the CMS, they have to understand how Alchemy works for end-users AND admin users. As I've learned Alchemy, I've used the Admin interface regularly to see if I'm including the right elements for the right customizations.

I don't think the guides need to offer a full admin-user focus, but some things aren't as intuitive and a sentence in a guide is always better than 2 hours of trial and error.

There's a case to be made for a separate Admin users guide, which could be helpful for developers training their clients to manage their new site, but for me, it is a lower priority than a v6 guide.

chiperific commented 1 year ago

Since we're so far behind on documentation, and it seems like you're already thinking about moving away from Vuepress, I suggest using Read the Docs.

tvdeyen commented 1 year ago

@chiperific we migrated to Vuepress v2. Would you mind to rebase with latest main branch?

tvdeyen commented 1 year ago

@chiperific regarding images, please refer to the Vuepress guide https://v2.vuepress.vuejs.org/guide/assets.html#relative-urls

Generally I think images are great. In this case I would add them as a subfolder into the guides section that uses the images. Something like this:

guides/admin/editing_elements.md
guides/admin/img/screenshot1.png
![Editor Screenshot](./img/screenshot1.png)