expressjs
Move version 2 to a subdomain
Just like other documentation practices, keeping this version on a separate branch with a different subdomain would be beneficial for historical purposes and to avoid cluttering the main documentation that is subject to changes.
I think that is a good idea! We can have a look in our infra and try to do the settings for this. What do you think @crandmck?
By separate sub-domain, do you mean that all the 5.x doc would be at something like v4.expressjs.com? This is an interesting approach, but differs from what we've been doing, where each version's API reference is maintained separately, e.g. https://expressjs.com/en/4x/api.html and https://expressjs.com/en/3x/api.html while the rest of the documentation is for the current version (4.x now, and once v5 is released, it would be 5.x).
...to avoid cluttering the main documentation that is subject to changes.
To be clear, changes are primarily in the latest/upcoming version (5.x). The older version(s) that are in bug-fix/maintenance mode typically doesn't require doc updates so the docs docs are basically "frozen" (except for stuff like correcting existing errors).
This idea is worth considering, since of course we need to maintain 4.x docs to help people maintain existing v4 apps. However, once 5.x is released, we don't want to encourage anyone to install or use v4 as a "new user" so we'd want to remove all the v4 "Getting started" material. If there's an argument for keeping it, I'd like to understand it.
All the info under the "Resources" menu is not version-specific, and duplicating it is not a good idea. Exception: I'm not sure about the Middleware. I assume most middleware will be usable by either v4 or v5, but perhaps there are special cases?
Most of the info under the "Advanced" menu is best practices (e.g. security and performance) which are not likely to differ much between v4 and v5. I'm not sure about Developing template engines -- it may need updates for v5, but I presume we don't want to encourage people to create new template engines for v4, so I suspect we should keep only a version for v5.
So, for the most part, the only v4 doc that should be maintained/duplicated is the API doc and everything under the "Guide" menu (modulo the migration guides). Since we already version the API docs, this proposal boils down to also versioning most of the "Guide" material. Does it make sense to have a subdomain just for that?
@crandmck My idea was that this change should be only for version 2, since it’s a version that follows its own style, structure, and content (guides, screencasts, and applications) on the website. Version 3 and later should remain as they are
Ah, sorry I misread the title somehow...
Honestly, I would prefer if we could just remove the v2 docs. It's so outdated, and doubtful that anyone is even using it still. When v5 is released, it will be 3 major versions behind. I don't think it's worth spending much time to maintain it, so I'd vote to remove it altogether. We should get consent from the @expressjs/express-tc , though.
Can we delete all the information about version 2, or would you prefer to move it to a subdomain?
@expressjs/express-tc I need consensus in order to move forward with this.
@expressjs/docs-wg, what do you think?
seems safe to get rid of it. if nothing else, we could put a link to the archive.org copy of it if someone really needs to see it
Agreed we can remove. Rather than an archive.org link though I think we could show how to run the docs site at it's last state? I dont think it is worth a lot of work, but having a backup from in the repo seems better than relying on the archive.org stuff since that has been having trouble being sustainable lately.
@wesleytodd I don't quite understand your idea, although I created a new branch called 2x, is that what you were referring to?
i can’t really comment from the tc side but as an average-joe express user i’ve never used those. would be nice to remove them from the doc site code too.
would be nice to have access to v2 in some fashion on the internet still. archive sounds good. would site backup way require user to clone and run? or just read on our github?
we can set up a redirect to the 2x branch. I wonder if there's a way to protect that branch so it can't be deleted.
I don't quite understand your idea, although I created a new branch called 2x, is that what you were referring to?
Yeah that is probably the easiest way, and then add instructions somewhere that say "to view the 2.x docs, clone the repo, check out the 2.x branch, and run npm run start" or whatever it necessary to run them locally.