Hacker News Reader

Comment by mrchess | Hacker News Reader

Can you actually host the old documentation this time and not leave us in the dust like you did in the 1.4 => 2.0 release?

View on HN

For that release we had an upgrade guide. It wasn't the most complete, but I think it helped a lot. For this one, as is the case for every other release, just browse the tags and download the docs. Just as it's not terribly difficult for us to host them, it's not asking much for you to download a ZIP file that will always be available :).

How do you recommend I link someone else to the exact docs (in lock-step with tutorials, etc.) going forward?

By the way, Node.js does an awesome job of keeping documentation (and landing pages) online for every version: http://nodejs.org/docs/

direct link to download it: https://github.com/twitter/bootstrap/zipball/v2.0.4

It's still available in the source.

That is not enough. Old documentation MUST STAY ONLINE.

How can that possibly be not obvious?

It does "stay online". Why must it also be hosted for you? When you download Bootstrap, you get all the docs in a folder. Open the index in your browser. All the old versions are tagged on GitHub and can be downloaded forever.

So when bootstrap releases a new version suddenly everyone must switch to self-hosting their docs? Because leaving the friggin' docs online costs so much?

It's inconceivable we are having this discussion on HN.

It's inconceivable that projects are expected to host old docs forever. Jesus, it's in the zip that you get if you download the Github snapshot anyway. It's literally 20 seconds of your time to have your own local copy.

There is a big difference between forever and switching it off as soon as you change versions. Most people were still using 1.4 when 2 came out so leaving the documentation up for a year or something would not have been difficult.

python & django both host old docs for all in-use versions seemingly forever. Nobody's complaining that they're polluting google, or campaigning for them to be taken down. So why are people reflexively resisting a reasonable request for bootstrap 2.0 docs to stay up? status quo bias!

All of the documentation for old Haskell packages on Hackage are hosted online and it does pollute Google's results. Google often links to outdated versions and you have to take a couple steps to find the current version.

I really don't see the problem. You have to download the release to use it and the documentation is included, what's the huge deal about keeping a tiny HTML file around? It's not like you suddenly need to start renting a VPS to read it..

> Because leaving the friggin' docs online costs so much?

It's not so much about cost but about polluting the Google index with obsolete information. For example, look up a Java API and it's very likely that the first link you will get will point to Java 5. Google is not wrong, that API link is most likely the most linked to, but it's very often not the one you are looking for and certainly not the one that the author of the API wants you to find first.

Have you actually tried to do that? BS 2.0.4 pops up with "framing not allowed!" and redirects to a missing page on the internet.

Probably relatedly, some/much of the docs rely on javascript, so they won't run unless you're running through a server. Instead of forcing everyone who wants or needs to see an older version of bootstrap docs to wrangle this non-working stuff in to a server and configure that, massive amounts of time would saved by simply having versioned docs online.

EDIT: the short answers is not to open the index.html file but any of the other .html files (examples, etc) and you should be able to at least navigate around some.

EDIT2: At least some of the javascript stuff is working without loading from a server - not sure why yet, but it's working. The index page still needs to be fixed.

Yes, I did actually try to do it. The popup is only on the index page, from one of those dynamic Github watcher-count widgets, and can be ignored by either opening the page of documentation you need instead or holding down escape, or deleting the offending widget.

I'm not sure what you're talking about with the JavaScript. JavaScript runs on the client, not the server. Twitter hosts these docs on Github Pages already... static files, no server-side code.

An error on the index sends off alarm bells, and I bet others never bother to try the other pages - just thinking "this is broken".

I know where JS runs. I was conflating embedded javascript references as <script src="http....> style javascript. Typically when I am doing JS, the JS is marked up as being served from a domain - an initial assumption would be that it would be trying to pull the js from a server, but it's not (or not caring, or my stuff is cached).

I still side with the others who want/expect hosted and versioned docs from a project of this size/influence.

I ran into the same issues you did, went ahead and compiled the archive docs here - http://unofficial-twitter-bootstrap-documentation.com/

I'm amazed by your sense of entitlement.

While the attitude is a little entitled, there may still be a valid point for other users as well. Couldn't se properly crafted URLs on the homepage solve this problem? Like /tags/2.0/documentation/index.html [1]. And run it right off of bootstrap?

Edit: the point being that we can point links at pages from previous commits, branches, and tags Shouldn't this help?

[1] that URL was slightly bastardized but I'm sure someone could very quickly whip this up

Boy I was half asleep when I wrote that comment, all I was saying was that since github lets you reference previous versions of files by crafting the URL properly to include a tag/branch/hash, it should be possible to link to previous versions of the documentation straight from the latest version, eliminating the need for someone to clone the repo to access them.

Python, Django, Ruby, Rails, Node.js, jQuery all have multi-version docs online. I'm sure there are plenty more examples. Yes, I do feel entitled to having support for outdated but still relevant software. This is standard.

The latest version of bootstrap only just got released. I think a majority of users will still find the old docs relevant, even weeks later.

Yes, I realise I can still download the docs. But it's more convenient for some people to have it hosted online.

Because I ask them to make a folder on their webserver and put the old docs there, which is going to take them all of 5 minutes?

Yes, sometimes people need to be reminded of basic common sense. I do feel entitled to that.

Please make it available online, or at least someone should make it available online.

You can clone the repo, check out that branch, and open the docs in your browser locally. That's even better, since now you don't even need a network connection to access it.

Having a copy that you can access locally is great, but there are advantages to having it online.

First, it means you can navigate to it by googling "bootstrap 2.0 documentation". If you are using five JavaScript libraries, it can be annoying to have to find the folder for documentation for each library.

Also, you might not even have the documentation locally. Another developer might have set things up and they might not have checked the documentation into version control.

Not to mention that any old tutorials, blog posts, wiki pages etc -- now link to 404 land.

While it would be great if everyone could just magically upgrade, if you've spent a lot of time wrangling some content management system to the "old" bootstrap, you're more likely better off fixing bugs in that site, than upgrading and hoping nothing breaks.

If it's supposed to be used as a framework, I'd say it's common courtesy to provide the old documentation for at least a short period. It's not that hard, see eg:

http://www.python.org/doc/versions/

Not cool guys. I can't actually open the docs that I downloaded because I get a popup that says "Framing is not allowed!" and redirects me to a non-existent Github URL.

Reply on news.ycombinator.com