#5582 - v11 tutorials addon should be completely separate from the v10 one

Actually this might not be a great idea as the addon goes further than just simple docs.

Perhaps instead of making this a separate v11 addon, we make the addon version aware. So there would be one tutorials addon but capable of serving multiple versions / zones via parameters. Each table would need to have a new column specifying which version a tutorial applies (v10 would have a blank value since it's just "docs" but v11 tutorials would have "11" as the value, etc).

Another idea is to separate the docs system out into logic versus pages:

* composr_tutorials addon is modified so it just contains the core logic of the tutorials system. We strip it of all the actual tutorial pages etc. Also make it version aware just like I mentioned in my previous comment.
* The documentation is broken up into separate addons... so v10 docs will be composr_tutorials_docs_v10, v11 is composr_tutorials_docs_v11, and so on. These addons contain ONLY the actual documentation assets (Comcode pages and images), but no logic. All the logic is handled by composr_tutorials.
* Make all the docs addons require the base composr_tutorials addon (necessary of course for the logic).
* Just like in the previous comment, new column on tutorials tables indicating which version the tutorial belongs to... except make it the addon name instead of the version number. If that particular doc addon is not installed, red alert it (or we could just return 404 not found).

That way, we can easily separate docs out into separate addons by version without running into complications with conflicting logic between addons.

We used to put different versions of docs in different zones. It had many issues:
- It was too much of a maintenance burden because the implication is we either need to actively upgrade those pages to new versions of Comcode when compo.sr is updated, or lock Comcode compatibility
- It's easy for people to end up on the wrong docs and would have been a lot of work to implement a clean navigation and clear communication what docs people are on.
- If we find errors or holes in the old docs, are we supposed to keep updating them? If not, quite possible people are better reading docs for the newer version even if they are not accurate, as a lot of new work would have gone into them that would apply backwards too.
- URLs would be version-specific, so with each version we'd lose all the "link juice" of any third party links
- There is the issue that there is a lot in the old docs that just tends to rot, references to dead technologues, broken links, etc.
- Supporting cross-linking correctly using things like the 'page' Comcode tag is difficult because it has to correctly link to same-zone regardless of caching, even in outside-of-zone contexts like search results.

Since then our docs system has improved a lot. You identified some of the problems with the database structure, which was not designed for multiple versions. There would be additional issues, given we are taking in contributions - do we allow people to contribute to docs for old versions, if that's what they're writing? What do we do when people start complaining that docs aren't being upgraded to newer versions because some contributors are just incentivised by our ecosystem to camp out on the older ones? If we don't allow contributions to old versions, what do we say when users or contributors are complaining about it?

[start - This next bit doesn't apply to your use case of wanting alpha docs up, but applies to the general situation of keeping up multiple sets of docs over extended time]

Also, at the end of the day we want people to be upgrading, so the happy path and investment should be going into what is new - if people don't want to upgrade, I think the maintenance burden should be them, not on the core team just having to maintain more and more history over time. We're here to develop technologies, not invest a lot of effort in free legacy support. If something seems burdensome to the core team and isn't driving the product forward, I do think we need to ask who is going to contribute all that effort / fund it.

So, personally I would not take the approach trying to keep updating old docs as first class content on our site.
Other projects do. For example, you can access the MySQL manual for many versions back. But those are simple static HTML pages.

[/end]

I'd question the assumptions about needing proper online docs for an alpha version. People who want to use an alpha version could also browse the actual files on Git. People on older versions could use archive.org, or also Git.

Other projects nowadays often use Markdown, and don't really have any coupling with their CMS and the docs they are providing, it's just all directories and files rendered by some third party markdown renderer combined with a navigation builder.
There would be some advantage to us doing that, but the big disadvantage is we would not be "eating our own dog food" anymore.

Anyway, my suggestion would be simply to host v11, along with its docs, on a separate website. Perhaps just compo.sr/v11-alpha, which would be a fork of the composr_homesite branch with its own config and database, and perhaps itself upgraded to v11 at some point as a test bed prior to the main compo.sr site being replaced (which I was planning to move to composr.app).

One of the main reasons for this issue is that v11 has links to compo.sr/docs11 in the helper panels. It wouldn't be intuitive IMO to have alpha versions up and these links still going nowhere. The docs (at least the ones we've updated) could be a good resource for others who are playing around with v11 to learn about it and what it can do.

I probably failed to mention but the idea would be to remove the docs of versions no longer used. So once v10 is no longer supported, we'd remove that.

I thought about a temporary v11 site as well and hosting the docs there. Then we run into confusion about user accounts etc (though that can easily be disabled on the v11 site). I am a bit confused when you say "host v11, along with its docs, on a separate website", but then say "Perhaps just compo.sr/v11-alpha, which would be a fork of the composr_homesite branch" (which would be v10, not v11). So not sure if you're suggesting starting with a v11, or starting with v10 and upgrading it to v11 as a test as you also mentioned.

---

Anyway, I suppose the larger issue here is that v11 has docs11 links in the helper panels which go nowhere. I could perhaps temporarily disable them until v11 is released, or, if the composr_tutorials addon is installed, have them link locally. Then there's the idea of hosting a separate temporary v11 site on compo.sr just to house the docs (disable everything else). I'm not sure housing a v10 fork will be a good idea because that will confuse users with how similar the sites look, but it's something we can do solely for v10 to v11 upgrade testing when we get there.

Will discuss some of this on Skype, but some quick replies here...

"v11 has links to compo.sr/docs11 in the helper panels" - the brand base URL can be changed.

"I thought about a temporary v11 site as well and hosting the docs there. Then we run into confusion about user accounts etc (though that can easily be disabled on the v11 site)" - yeah I think accounts should be disabled (and existing ones imported over later). I think given the lateness of v11 and my continued lack of availability people would understand if things are a bit rough until it's done. So we can just put in a match key permission denied message when someone tries to join or login saying the v11 site is currently read-only and in development while v11 is in alpha.

"I am a bit confused when you say" - the subpath I gave was meant to be for another site under the same domain, not a zone.

"starting with v10 and upgrading it to v11 as a test as you also mentioned" - based on what I'm going to say to you on Skype, maybe it's just time to get a rough v11 site running v11 on composr.app.

Closed as no longer relevant; we're using a separate site