Documentation upgrade

[tostasqb]

Hi all,

A common concern from fellow colleagues is that the documentation could be better. It's hard to find answers although a special thanks to @owen2345 is more than deserved for trying to be on top of everything.

This ticket is just to try and have a discussion, if anyone else has the same kind of feeling/feedback and if there's anything that can be done to improve it.

Would love to see the project take off, improvements in design are also a topic for a (separate) discussion.

[brian-kephart]

What kind of documentation are you thinking about? README, http://camaleon.tuzitio.com, or something else?

[tostasqb]

Starting off, devise has a good wiki, the how-tos are particularly extensive. sidekiq also makes use of github wikis. This could be a starting point and it provides easy extensibility, making it available for anyone to participate building.

Having said that, having a documentation engine could be a solution too, made out of .md files. I'm thinking Rails Guides are a form of that but haven't searched to know, but read-the-docs, docsify or/and making use of github-pages can also be solutions and makes it open for contributions as long as we make it available on a public repo

[owen2345]

@tostasqb I completely agree with you. Unfortunately the cms is becoming obsolete and difficult to keep updated with my horrible old code :D (8 years ago: my first ruby code).
It should be rewritten using rails for api (rest or graphql) and react or angular for frontend.

[brian-kephart]

@owen2345 give your old code some credit, it's made our lives a lot easier :)

Honestly, I've been thinking for awhile now that we're due for a v3. Remove support for old Ruby/Rails, switch the uploaders to ActiveStorage, remove unmaintained dependencies (will_paginate-bootstrap), get rid of Bootstrap and jQuery, switch from sprockets to webpacker. And, of course, refresh the docs.

That's a ton of work though. @owen2345 is the only maintainer, and there are few contributors. I don't know how we would get it done.

[tostasqb]

Making a cms from scratch is a big job and that's why we don't see many options in ruby/rails. I do agree the project looks like it's going downwards.

I would love to see all those changes @owen2345 and @brian-kephart , but I don't know if everyone has the time to invest in it. I suspect not speaking for myself. It's a big lift.

Iterating in what we have seems the only viable option. Furthermore, I'm not unhappy with sticking with the basics of a current rails monolithic architecture. Works well and doesn't compromise, meaning I would maybe invest my efforts supporting assets through webpacker.
But that can be a big task as it is. In order to update the project's "face" my opinion is we change docs (maybe deleting the website altogether) and improve the the cms's frontend so that it looks up to date.

[brian-kephart]

@tostasqb Have you seen this guide? I'd always wondered how to do engine assets in Webpacker, and I just discovered the guide. Looks doable. It might be a breaking change, though.

As far as docs go, I think the main thing that would lead to improvement is to keep them in some form that accepts pull requests. I don't think the docs at http://camaleon.tuzitio.com/ have a public repo, so it's up to @owen2345 to maintain them on his own. If the docs were in a public repo in any of the forms you suggest then we could improve them as we go. I haven't used any of those types of documentation as a contributor, but a Github wiki seems like a natural fit since the repo is here.

[texpert]

@tostasqb , @brian-kephart and WDYT about Webpacker's coexistence with Sprockets, as it is currently the Rails-way? Here's a good article with useful links to other discussions and resources.

Though, maybe the situation will get better with Webpacker 6.0 - several bugs are being fixed currently in the master branch. Reading through these fixes even brought me to think that using Webpacker prior to 6.0 version would be a pre-mature decision. It was said that it was slowing not only the compile time because of node_modules compilation, but actually was surprisingly slowing the production server.

So, I'd propose to try for the start using Webpacker only for JS packs, and using it from the master branch.

[brian-kephart]

I feel like I hijacked this issue. Sorry everyone!

I started #966 so discussion here can stay focused on documentation. @texpert please see that issue for my opinions about Webpacker/Sprockets and to discuss further.