Change default h5bp download to stripped

[paulirish]

I think we're at a point now where we could change the default download to stripped, and provide an optional package that is h5bp-documented with all the comments.

Thoughts?

Side wish, I wish there was an easy shell/node script I could use to stripped-ify the git repo.

[mathiasbynens]

Why? IMHO, this would only make the default H5BP download more magical (“Why is this line here? Oh, if I remove it, x and y break! Better not touch it.”) and less educative.

[yanneves]

Must agree with @mathiasbynens there... imo the boilerplate should be understood, not taken for granted as magic. Performance advantages of using some (automated) build process to strip comments, etc are already noted (and linked) in the h5bp documentation.

-

[drublic]

Yes, I agree with Mathias, too. I personally like it when I go through the index.html, looking for stuff I can kick out and can directly use the links provided to go to the docs-page for additional header-info.
As @Aaunel points out a build script decreases the pageload and removes comments and stuff. I think if developers don't remove comments for productive mode it's not our thing to take care of (same as with selection-color).
Is there a reason you don't want the additional info in there anymore by default?

[mklabs]

Hey there

@paulirish I've setup a really basic gruntfile + html-striping-comment class through html-minifier. Maybe that fits what you're looking for here :) (→ https://gist.github.com/11b15861be04ae8f4a50) A little "quick-and-dirty" but it should work.

[paulirish]

Hans, Mathias,

Yes the default would have less docs. Of course. I think the project is old enough that most of the people using it have touched it before.. and learned all the tricks.

The docs are still 1) in the doc'd version 2) in the github repo (master) 3) probably in the real documentation .. so they still seem accessible.

If you want docs though, you pick the doc'd version.

as for why..

It just feels a little old and stuffy.. heavy even to keep them around in the default. H5BP is stable enough that it is actually "boilerplate". Let's drop the superfluous extras and settle on the basis.

[yanneves]

@paulirish you make a good case... many libraries and frameworks ship as a production version by default, with a separate, commented, development version; don't see why H5BP should be deployed otherwise.

Can't argue that the documentation for H5BP available online is extremely thorough. :) +

[drublic]

You are right: H5BP has "matured" to a level where people know what it is good for.
At the moment some devs use the package as provided in productive mode – again @Aaunel stated this before. For these devs it would be better to have a striped version.

I use the Ant Build Script to remove all "trash" so I can only speak for people using a build script.

As it turns out most of the people using H5BP do not use some kind of build scripting (survey of devs). This leads me to the conclusion that it would be better to use at least some kind of striping for the default version. And as you described, Paul: the un-striped version is still available.

In favor of "new is always better", I'd say lets try shipping the striped version by default. If ppl complain about it we could go back to un-striped.

[mathiasbynens]

I still stand by my previous comment.

I think the project is old enough that most of the people using it have touched it before.. and learned all the tricks.

How would you know? Any data on that? Or is it just a gut feeling?

I use h5bp as a starting point whenever I give an “HTML5 workshop”, and for newcomers the comments are highly educative. If stripped became the default I could just point them to the alternative, non-stripped version, sure — but that only complicates things more for people who are new to the project already (and who could use a little help / extra info).

Devs who feel they’re familiar enough with the project to get rid of all the comments can just download the stripped version. Everyone else is better off with the commented version, IMHO.

[yanneves]

The project's maturity doesn't necessarily indicate global adoption, so there's definitely a volume of new users to consider. @mathiasbynens, you could say this for a number of frameworks and libraries, I suppose the only difference here is that you're working inside boilerplate source, not building entirely on top of or alongside it.

What impact does a default option have here? Is this for the h5bp.com site or are there other single points of entry that would link to either a stripped or un-stripped version of the boilerplate? For example, the options to download as they are now ("Default", "Stripped", "Unstripped") seem fine.

What's the current volume of downloads of the two versions. Perhaps the default should just be the most popular of the two? Like @drublic points out, it's difficult to make assumptions around the level of developer downloading the boilerplate, so traditionally you would adjust mainly to accommodate new, unfamiliar users.

[paulirish]

I just added analytics to see who is downloading what. h5bp/html5boilerplate.com@deca4d2...e241f7d

we're already tracking the custom builds.. i have a summary of past 30 days of custom builds here: https://docs.google.com/spreadsheet/ccc?key=0ArK1Uipy0SbDdGtmOUZ4QTBYQmpuWHBLUGJEOWNIU0E#gid=0

if anyone wants to summarize that.

[bkvirendra]

Yeah @paulirish has a point since h5bp is enough popular & is being used very regularly & a stripped would surely help as an alternative for the main package (with all the comments & docs in it) !

[yanneves]

@paulirish anything conclusive since implementing those analytics? :)

[paulirish]

Ack. my fix didnt go in last week, but here is analytics for the past few hours:

Basically: 70/30 split of default/stripped.

[tomByrer]

That is a large % for "default"! May I guess that some of that % is due simply to "default" being the first link?
Maybe for now, make the "stripped" download button large & > CLICK HERE < (eg a de-facto "default", & make the "default"-commented package link much smaller & text-only, after or under the "stripped"? Much like how some web apps' pricing pages list the "free" account in small print.

Then you can see how much real demand there is for a commented .zip.

[mklabs]

Idea (might be silly, ignore if it is)

• Switch default to stripped version.
• Includes a docs folder with the unstriped version
• The docs folder may also include the whole h5bp documentation, either as markdown files from wiki or pre-rendered html pages

I've seen some requests on h5bp.com/docs comments for making the doc available offline.

[yanneves]

@mklabs Not a bad idea, imo, but just to clarify do you mean the other way round. Stripped version (no comments inline) would come with a separate documentation package (.md files would make sense for this).

I think treating the h5bp as more of a framework and pushing out a 'no noise' version makes sense, as long as contextual comments are kept in place. So, displaying sections intended for user interaction (e.g. "css goes here") would not be affected. The documentation is very clear alone. Imagine if jQuery was shipped with inline comments by default?

@paulirish anything new regarding the stats, or have those percentages remained pretty much the same?

@tomByrer I had the same thought regarding a user's inclination to choose the 'default' option since it says 'default' ...if possible, it would be worth trialling each option as a more exposed call-to-action

[drublic]

The stats are for the website?! There are three buttons which all look nearly similar. If 70% of downloads are the full package I don't see any reason to change it.

In this case "switching to stripped version" would mean to change the files in master only?
At the moment it's not clear to me what exactly should be changed as I don't really know what the default download is. How about other?

Including the whole documentation from the wiki requires a build-process for the package I guess. But I like the idea of making the documentation available offline.

[yanneves]

@drublic 70% of downloads are for 'default', which happens to be the full package ...I'm guessing the master would still remain full and you'd have some kind of distribution (dist) directory or branch? Still quite on the fence about this one, myself, but don't see why it's not worth investigating a change thoroughly. :)

[drublic]

@Aaunel Well, here are the buttons from the website. Which one is the default? (I know it's the left one. But the others look the same, right?)

[yanneves]

@drublic yep, I see what you mean, so the results shouldn't be shifted much, especially given the 'stripped' version sits in the middle... however, what if it said, download... "Boilerplate 'Unstripped'" and "Boilerplate" - would that make a difference? Worth checking the results of a change like this.

My other question still stands, too. Are there download links elsewhere, that can only point to one version?

[tomByrer]

I was thinking more like this, though perhaps with icons to help clarify & spruce things up: http://d.pr/i/I66O

<p class="dwn">
        <span><a name="production" href="http://github.com/h5bp/html5-boilerplate/zipball/v3.0.2stripped"><u>Download</u> "production"</a> <small>Stripped clean of comments, just the bizniss.</small></span>
        <br><i>or</i><br>
        <span><a name="development" href="http://github.com/h5bp/html5-boilerplate/zipball/v3.0.2"><u>Download</u> "Development"</a> <small>Stuffed full of docs, hints, and links</small></span>
        <i>or</i>
        <span><a href="github" id="builder-custom"><u>Fork at Github</u> "Source"</a> <small>Contribute patches, view in the raw.</small></span>
        <i>or</i>
        <span><a href="#builder" id="builder-custom"><u>Roll your own</u> "Customizer"</a> <small>100% hipster.</small></span>
      </p>

Might not need the "Contribute on Github" text link below the "source" link.

[necolas]

Isn't this more of an issue for the .com repo? Redesigning the site in general is something I hope to kick start at some point.

[tomByrer]

@necolas Yes, it seemed to morph in more of a webpage thing.

[paulirish]

updated stats after 5 days and 2400 downloads:

documented: 70%
stripped: 25%
custom: 4.5%

jonathan reported he gets 1800 DL's per day on initializr, actually, so
maybe we're solving the wrong problem?

[tomByrer]

How many of those DLs at initializr are unique IPs?
Maybe people are downloading the "wrong" build for them at first, or just want to compare & contract versions? Or maybe initializr.com is simply a more popular URL to visit?

[yanneves]

@tomByrer I could be a few of those statistics, got quite excited with the pick & mix prospect :) ... I like the structure above - Production, Development, Custom

so maybe we're solving the wrong problem?

@paulirish what do you mean by that?

[tomByrer]

@Aaunel Thanks, I stole "Production, Development" from jQuery. I figured there was a good cross over of target markets.
However, jQuery's own docs say "Minified, Uncompressed". Hmm... well the order is consistent.

[karlpcrowley]

I'm sure the community wouldn't mind doing a survey?
Issue #1050 could be thrown into it as well

It'd be nice to know how many people use .htaccess and remove the meta tags

[necolas]

In some sense, we maybe shouldn't even be providing a "stripped" version at all.

I'm not a fan of stripping CSS comments and formatting. It should be part of a build step and not the basis for development code. That only leaves us with the comments in index.html, and it feels unnecessary to have a branch just to remove a handful of HTML comments from one file. If those comments feel excessive (which I think is a concern several of us have), then we should strike a better balance between comments and code.

The idea of including docs in the main repo is interesting. I've found it to work well for grunt. Benefits:

• Any version of the project that is downloaded would have docs that match its code. No issues with the wiki being out of sync with stable releases or older releases people might be working from. This will be especially true as HTML5BP is included in package managers and other software that provides software bundles.
• Any change to the code would have to come with a corresponding update to the docs.
• Easy offline access.
• Helps address the drawback of removing HTML comments, because the documentation will be packaged with the code.

Drawbacks:

• Adding things to the repo again. But maybe this is important if the outcome is better documentation.
• Some work and planning around how to modify the existing wiki. We'd still keep the wiki for all the pages that aren't strictly about code in the repo.

[mathiasbynens]

+9001

[sindresorhus]

⬆️

[paulirish]

I'm not a fan of stripping CSS comments and formatting. It should be part of a build step and not the basis for development code.

As a repeat user of the H5BP, I get tired of looking at those HTML comments and exhaustive inline CSS documentation. Your first few times with it, you'll look things up and learn new techniques. After a while you trust the platform and go with it.

After this point, the comments (and additional whitespace) are in your face and slowing down your development. I want the comments in the source to be unique to my app and communicative about whats going on inside of it, not what's going on in my dependencies.

I still think the dev branch should be with comments inside it, but I'm just proposing that return users have an easy way to download stripped. That and I hate perpetuating the reputation that H5BP is large and bulky. :/

[baamenabar]

That's why I keep coming back to H5BP, inline comments. (And why I recommend it to other people)
First time user will not likely be looking into the branches, and comments give assure to new users. Regular users, with just a small nudge (link), will know where to checkout directly from the stripped branch.
Then again as a returning customer I'm OK with looking branch for the commented version.
Though I'm amazed at how little people download a custom version.
Just my two cents.

[necolas]

As a repeat user of the H5BP, I get tired of looking at those HTML comments and exhaustive inline CSS documentation. Your first few times with it, you'll look things up and learn new techniques. After a while you trust the platform and go with it.

Those CSS comments are largely from normalize.css. In your dev code, there should be clear comments. Nothing worse than being introduced to a project/site codebase and there being inadequate comments there and no one who remembers why certain lines of code were included.

Given that the base CSS is full of workarounds and browser normalizations, it's important for it to be clear why each line is there (and why you may or may not need it depending on your support matrix)...not just for people working on this project but for other developers who joint teams that use HTML5 Boilerplate as a base for their site.

After this point, the comments (and additional whitespace) are in your face and slowing down your development. I want the comments in the source to be unique to my app and communicative about whats going on inside of it, not what's going on in my dependencies.

Part of my drive to split the CSS into separate files is to avoid mixing various presentational layers and parts in a single file. Other than that, I don't really think this is a problem. If you're writing your app's CSS code you shouldn't really be doing that in the same file as normalize.css or print styles.

As for the HTML, I'd be in favour of reducing the number of comments there because I don't think many of them add value. Some are stating the obvious or would be better kept in a bundled docs/ directory that replaces the sections of the wiki dealing with project code.

I hate perpetuating the reputation that H5BP is large and bulky. :/

Since removing demo/, test/, build/ and other bits and pieces, I don't think that reputation exists anymore :). I've never had any complaints about the comments in normalize.css. But I agree with making it more obvious that index.html is pretty slim, by removing excessive commenting in that file. Other efforts, like moving the icons into img/ (esp if we think of future Metro and retina icons on the way) and breaking up the CSS could help to increase the appearance of simplicity and order while actually increasing functionality and ease of subsequent development.

[necolas]

Closing now. Would like to look into avoiding a stripped branch going forward.