Express 2x docs gone from expressjs.com

[elliotf]

Hello nice strongloop folks. I see that in #212 the docs are removed without a reason for why other than they're old.

Not to draw comparisons, but http://api.rubyonrails.org/v2.3.8/ hasn't been updated since 2010, but it's still up and available "just in case."

Deleting things just because they're old seems a bad precedence.

[diversario]

👍

[jalcine]

👍 let's not break the Internet. Comcast is doing enough of that.

[dougwilson]

Are you seriously asking for the 2.x documentation to be re-added (express 2.x has been unsupported for over 2 years and is full of security holes), OR are you asking for the old 2.x URLs to redirect to some place useful?

[elliotf]

Either way would be fine, I think. The main goal is to have earlier documentation at a stable, known location. Please see my very relevant example of rails 2.x documentation.

I also hope that the 3.x documentation stays around even after it's not been touched/updated for two years. I'm sure you are all smart people and can come up with a good solution.

[arodland]

@dougwilson General internet good practice says don't break well-known links without a good reason (and there isn't one). Good project stewardship says that if you don't want to maintain something, leave people the resources to maintain it themselves. Just because a library goes end-of-life upstream doesn't mean the applications using it magically disappear.

[dougwilson]

@arodland I did not remove the documentation, only suggested that it could be removed. StrongLoop maintains the documentation now, and I don't do anything with this site, so there is no need to act as if I personally removed it in your comment. You can always view the removal here: 661047f

@hacksparrow it sounds like people really want the 2.x docs back. Is that something you can do?

[hacksparrow]

Waiting for a confirmation for its restoration.

[arodland]

@dougwilson I didn't mean to imply that you were personally responsible. Sorry!

[dougwilson]

It looks like @hacksparrow is asking for the ability to add it back, so it sounds like there is progress here and this issue has not been thrown out, so we'll just wait for now (remember, StrongLoop is paying for these docs to get improved for everyone and so bringing it back does have a cost, since the entire site is being re-done; including 2.x will require extra money).

By the way, everyone, so far I've just heard that "oh, it was there before and look at Rails!". To help make the case, can anyone explain their reason for why they want the 2.x documentation back? Do you want links not to break? Are you routinely reading/referencing them? Something else?

[crandmck]

I guess the assumption was that since no one commented on #212 (prior to this), there was no widespread desire to keep them. Although the cost to replace them is nonzero, I don't think that should be the main determinant of the course of action.

I do think its reasonable to put something at http://expressjs.com/2x/ so that it's not just a 404, which is not very friendly, per @arodland.

I see two options:

• Replace the old 2.x docs as they were, but with strong warning that they are not maintained and with explanation of shortcomings of 2.x.
• Replace the URL above with page that explains shortcomings of 2.x, and with instructions to create the docs yourself 2.x from the GH repo, which should be relatively straightforward.

One thing that I don't think we should do is spend effort actually updating the content of the 2.x docs, since as @dougwilson notes, the code is not maintained and is long outdated, etc.

[elliotf]

@dougwilson please don't improve the 2.x docs. Improvements are not necessary

Why put it back up:

• It's the "classy" thing to do
• Documentation is historical
• People are still, for better or worse, either using or migrating away from 2.x.
• See comments from @arodland above

Non-rhetorical question: Are we going to have a similar conversation about 3.x documentation in N years?

[dougwilson]

@elliotf please do not direct stuff at me. Like I said above, I don't work on this repository, so I will never be "improv[ing] the 2.x docs"

[thefotios]

👍 for restoring the docs. Like most software/frameworks, you're inevitably going to have some legacy code out there that depend on them. While I highly, highly doubt anybody is doing new work in 2.x, there are probably plenty of teams that depend on it. Not all projects have the luxury of being able to just bump up a major version. Most times, it's most like "if it ain't broke, don't fix it". And then if it is broken, having the docs is much more useful than upgrading multiple major versions.

While there is a non-zero cost for hosting the old docs, simply tagging them as "Deprecated" and not improving them any further should be fine.

[crandmck]

BTW, regardless of which option we choose, we need to add a brief explanation of the known security issues (and any other relevant problems with 2.x) and link to https://github.com/strongloop/express/wiki/Migrating-from-2.x-to-3.x to encourage people to upgrade apps.

@hacksparrow please go ahead and replace the docs per option #1 in my previous comment. We can revisit later if need be.

[dougwilson]

Just so everyone like @elliotf is clear: I am not involved in the express documentation maintenance (nor have I actually ever been). The documentation is maintained separately from the code itself (thus why it's two different repos). The documentation is currently being lead by @crandmck and @hacksparrow who are very capable and (especially @crandmck ) actually have a background in writing documentation.

In fact, @hacksparrow @crandmck it may be useful to make a note of who the lead documentation maintainer is in the README.md file :)

[hacksparrow]

Alright! Restoring 2.x docs with the relevant warning and and information. @dougwilson thanks, I will let @crandmck take a call on the README.md :)

[elliotf]

Accidently closed.

[dougwilson]

@dougwilson People "like me" would be replying to you because you're asking the questions.

Yes, but you said "@dougwilson please don't improve the 2.x docs", yet if you read what I said, in no place did I eve say I was going to improve the 2.x docs, so why would you tell me not to improve them?

Perhaps the people who are leading the conversation should be the ones asking the questions?

OK, I guess I will never be commenting in this repo from this moment forward. I love how hostile people are.

[arodland]

@dougwilson no one is attacking you. You've been helpful. Thank you.

[elliotf]

@dougwilson I think you're reading more into my words than intended. No offense was meant.

[dougwilson]

@aredridel yes, thank you. I know Reasonable people do exist, and I alerted the appropriate people about the issue and they have responded.

The quip "Perhaps the people who are leading the conversation should be the ones asking the questions?" seems, to me, a bit hostile. I'm sure people reading this issue can see the progression of events: 2.x was asked back; after a few hours of no responses, I took time from my vacation to inquiry if the docs were actually wanted back, or just the URLs to work; people chimed in they wanted 2.x docs; I pinged the appropriate people.

@dougwilson I think you're reading more into my words than intended. No offense was meant.

OK, well, then I'm sorry for reading into it (it didn't help that you deleted your comment right after posting it). I do all this node.js stuff for like 0 dollars (technically, $7/week from some crazy people :) ), and I'm even on vacation this week, but I know the Internet does not take vacation so I put aside time to continue to respond. I was just trying to find out what you really wanted, rather than just taking it at face value, since I didn't see a reason listed other than "well, Rails does it" (and yes, lots of people do it; Rails isn't special ;) ) so the best course of action or you guys could be made.

[hacksparrow]

Restored with this warning:

Express 2.x IS NO LONGER MAINTAINED
Known and unknown security and performance issues in 2.x have not been addressed since the last update (29 June, 2012). It is highly recommended to upgrade to Express 3.x or to Express 4.x.

Let's move on.