bower.io v2

[desandro]

The bower site revamp is here. preview: bowerio.desandro.com.

Docs are now broken up into pages. To start us off:

• Home page / Getting started

• Creating packages - bower.json

• API - command line reference

• Configuration - about .bowerrc

• Tools

• About - contact, brand, logo

  This re-haul takes care of a bunch of requests that have piled up over the years

• add Getting started Documentation / Getting started #3

• uses Jekyll Consider relying on Jekyll / deployment #4

• use IA / redesign IA / Website Redesign #7

• Add logo & brand colors Brand guidelines #9

• Add list of tools using Bower Maintain a list of tools consuming/using Bower #19

• .bowerrc docs bowerrc docs #34

• Removes "By Twitter" from masthead, moved to about page remove 'by twitter' #37

It's not perfect, but it's a huge improvement over the current version (which is just a skin of the README). And, it gives us a base to build upon.

I'd like to merge this in the next week. This PR is more a head's up. Please let me know if there's anything that needs resolving before merging.

[rayshan]

Hi David, a few things that jumped out:

• Maybe a sticky sidebar like http://getbootstrap.com/css/#type? Would be a huge UX win
• I assume most users use bower for dependency management and need to tweak bower.json, the page "Creating packages" contain this info but the title is very specific, perhaps call it just "Packages"?
• Is it common to call CLI commands APIs? Perhaps the page API can be named CLI & API or Commands & API?
• Add gulp to Tools? e.g. https://www.npmjs.org/package/gulp-bower-files/

There are a few other minor typos that can probably be fixed w/ PRs after you merge this.

[sheerun]

Nice work :)

My vote would be:

1. Move everything from front page from "Install Bower" down to "Getting Started" section. Leave only paragraph explaining what bower is.
2. Creating packages is OK, but also link to new section "Package Manifest" or "bower.json" with content from Github repository: https://github.com/bower/bower.json-spec
3. API -> Command Line
4. Maybe "Configuration" -> "Bower Configuration"

[rayshan]

One more undocumented feature of .bowerrc - analytics, boolean, for programmatically enabling and disabling tracking, see here: https://github.com/bower/bower#analytics

[sheerun]

Also all command-line options like offline, quiet, force etc.

[desandro]

Thanks for the feedback! Sounds like the biggest concern is the organization of content & some page titles. In general, I wanted the titles and URLs to be generic where we didn't have to keep creating pages for related concepts. Bower is big, but its documentation could be contained to just a couple pages. Here's what I was thinking:

Home page

I'd like the home page to be useful, rather than a splash page. It should provide immediate value for new users who just landed on bower.io, rather than require them to navigate further.

Creating packages

This page is for creating packages and editing bower.json. We could move bower.json spec into its own page. I like this interactive spec for package.json http://browsenpm.org/package.json, That would require lots of additional work that I'd like to separate for now.

API

Currently, this contains both reference for the CLI and for using Bower programmatically (see bottom). The CLI is also the API for programmatic use, which is why I used the more generic title, API.

Configuration

Spec for .bowerrc. I concede Configuration as a title feels too broad. Would renaming it to .bowerrc be better? My concern is that it's not meaningful to new users.

Tools

This one is straightforward 😁

About

About the team, Contact, and Logo stuff.

---

This makes for 3 points to resolve

1. Should a bower.json page be created? (this can be done later)
2. Should API be renamed to CLI
3. Should Configuration be renamed to .bowerrc

[benschwarz]

I think that the "Configuration" title could stay, but maybe we open up with something like:

You can configure how bower operates for your project by adding a .bowerrc file to your project (or home) directory.

Which is short, simple and straight to the point. What do you think?

[rayshan]

@desandro thanks for the details. I agree that homepage should contain more than just the description.

Should a bower.json page be created? (this can be done later)

• yes, perhaps have a note in Creating Packages that say "for details on bower.json, please see Package Manifest / bower.json page" then include full content of specs per @sheerun. Yes the interactive package.json is way cool. Implementation is here: https://github.com/nodejitsu/npm-package-json-pagelet. It's not clear how it can be used without bigpipe. It really needs to be a web component...

Should API be renamed to CLI

• Probably fine either way. I like "Commands and API". For reference, npm calls CLI commands API, pypi calls them commands, rubygems has separate docs for commands and API, other tools that intermingle CLI and API call them all kinds of things (e.g. redis uses commands)

Should Configuration be renamed to .bowerrc

• agree with @benschwarz, keep Config

[tyrw]

@desandro I mentioned this to @rayshan a while back and I don't know if there's any discussion: in coming from a rails/backbone environment and recently learning about Bower, I didn't really know what was meant by "A package manager for the web", which made me initially brush Bower off and look at other tools.

It seems the target audience will be web developers, so perhaps something more specific or relevant would be best for the tagline? "A front-end package manager..." Obviously the site itself states in more detail, but for people researching through tutorials/blogs like I was, the authors usually just regurgitate the headline, so readers may not make it that far.

Anyhow, the proposed version looks great. I especially love the mascot and look of the page.

[desandro]

Merged!

@twler Thanks for the feedback. Yeah "A package manager for the web" is not clear in its purpose.

Let's open separate bugs for additional fixes.