soledad penadés

I love that, thanks to JavaScript's flexibility, and the fact that most of the code is meant to run client side --and thus publicly available--, lots of open source JavaScript projects are released every day (probably GitHub helps a lot, too). These projects range from the boringly rock solid and useful to the absurdly experimental, and it's all great, and beautiful! An amazing show of creativity, kindness and courage, by releasing stuff in the open. Which, in turn, encourages more competition and innovation. All great! Thrilling! An exciting time to be a web developer! Yay!

However, there's a but.

Boo. I'm pretty sure everyone has experienced this sensation: you hear marvellous things about a library, but when you get to its repository page... the horror, the horror! Tons of dotfiles, configuration files, lock files, build scripts, licenses, readmes, maybe bootstrap files, or package.json files, and maybe even the full source code, mercilessly dumped on the root directory.

I don't want to shame any specific project, so here's a couple of semianonymised listings so that you see what I mean:

design/
examples/
spec/
.coverignore
.gitignore
.jshintrc
.mailmap
.npmignore
.travis.yml
CHANGES.md
CONTRIBUTING.md
LICENSE
README.md
VERSIONS.md
minify
package.json
lib.js
lib.min.js
lib.min.js.gz
anonyfile.js
otherfile.md

and

browser/
lib/
tests/
.gitignore
.jshintrc
.npmignore
.travis.yml
CHANGELOG.md
component.json
Gemfile
Gemfile.lock
LICENSE
package.json
Rakefile
README.md

These probably are amazing libraries, although it's really hard to tell upfront.

I described this in another post, a while ago:

When I have a look at somebody else's project and all I see [...] is a myriad of files and folders and stuff, and I don't know where to start, I fear for the worst. If they can't get files organised, how will the rest of the code be?

The point is that you're adding friction by not paying attention to what people will see when they look at your project for the first time. Or the second. Or --if you're very lucky-- the third. Ever wondered why someone picked someone else's project B when your own project A was vastly superior? Maybe they had a neater project structure.

But what if some other project depends on your project? Or what if your project is the only one that fullfils a given need? The only choice for those users is either figure out how your project works and maybe even send you patches to improve it, or just toss it away and write their own.

So what do we want, a bunch of half-baked incomplete projects that all perform the same task more or less well, but have different undocumented build methods and etc, or several good projects that work exceptionally great and have a strong team of contributors?

Favour a task oriented structure

Have you ever heard of Miller's Law? It says we can only keep about 7±2 things in mind at a time. The two examples above had way more than that: 21 and 15. And those aren't the worst I've seen--only the latest I had visited today.

Hence, simplify your project's root directory. Paraphrasing myself again, what about having something like the following?

/build - a compiled version of your library/app
/docs - possibly in .txt so no compiling is needed in order to read them
/examples - demos of your library or sample files
/src
    /data - assets you need
    /libs - libraries you depend on
    /in as many folders as needed - your own code
    main entry file (e.g. main.cpp, index.html)
/tests
/utils - utilities for building and stuff
LICENSE
README
.gitignore (or similar)

See? exactly 9 items (7+2). It's neatly sorted out, it's not overwhelming and it's also very modular and task oriented: if I just want a compiled, minified version of your project, I go to build and pick whatever interests me. If I want to make changes, I go to src and hack at will. Then I go to tests and make sure all is still OK. Finally, utils has some script that generates a minified version for me.

Be considerate

This approach reduces the cognitive overload we all experience when approaching something new for the first time (i.e. makes all that new information manageable). By trimming down the number of things people have to look at when evaluating your project, you have probably won 50% of their approval--even if your project doesn't really answer their needs. Maybe they'll go back to it in the future, as in: "oh, this isn't what I want right now, but it looks interesting! Bookmarked!"

And you're also being nice and considerate by having a low barrier of entry. People can try your project almost right away, without having to replicate your coding environment first, and can allow themselves the luxury of not caring whether you're into grunt, yeoman, travis or whatever it is that is fashionable at the time of writing your library. Or at least, they don't have to care... if they are just end users.

You should always write a note in the README file explaining how to build your project, so the process of adding new features and building a custom version of it shouldn't be traumatic, specially if a user starts from scratch (i.e. without having a setup like yours).

The best part of it all is that by the time you want to use your project, months later, in a new computer (or after reformatting & reinstalling), you will realise you have already forgotten how did it work. But you'll just need to follow the very same steps you wrote in order to quickly get it up and running.

So if you really care about your project, its users or your own sanity in the future, tidy the repository up today! ;-)

(sort of continuing the series I started with Usable open source project pages)