What is the Humans.txt file?

/

I like the idea of the humans.txt file. It is a simple .txt file you can make available at the public root of your website which describes the participants in the creation of the site. This blog has one.

There is a de facto root file pattern in the historical evolution of websites. Robots.txt, Favicon.ico, Sitemaps (sort of), even the index.html file was a webserver idea that became the standard thing. Humans.txt exists not to direct crawlers, establish a website icon or as a default page when none are given, rather it is attempting to become the de facto standard for creator attribution. About time too!

It drives me crazy to see the creator's information anywhere on the website. Not so much if it is hidden in a comment in the markup somewhere but just overtly on the template on every page? Customers pay for work, not to be an advertising platform. That said, there are times where I do want to know who had a hand in the site creation. Humans.txt seems like a nice way to solve this problem.

Official Standard

Still, it is rather new, it's inclusion in the html5 boilerplate project is a milestone for adoption, but you still do not see it very widespread. Something I like to do before using anything like this is to see what other sites are doing with it first. How do they use it?

The standard humans.txt looks like this:

/* TEAM */
Your title: Your name.
Site: email, link to a contact form, etc.
Twitter: your Twitter username.
Location: City, Country.

[...]

/* THANKS */
Name: name or url
[...]

/* SITE */

Last update: YYYY/MM/DD
Standards: HTML5, CSS3,..
Components: Modernizr, jQuery, etc.
Software: Software used for the development

The official site does not seem dogmatic about the format. Suggesting the heading style but other than that not specifying much in the way of content format, mostly about file meta-information and placement.

Usage Survey

When I am unsure about how a de facto standard is actually being implemented, first thing to do is check how others are using it. So I looked around.

humanstxt.org

You would figure this is the ultimate humans.txt file.


/* TEAM */
Chef:Juanjo Bernabeu
Contact: hello [at] humanstxt.org
Twitter: @juanjobernabeu
From:Barcelona, Catalonia, Spain

[...]

Web designer: Abel Sutilo
Twitter: @abelsutilo
From:Sevilla, Andalucia, Spain

/* THANKS */

(First) EN Translator: Jos Flores
Twitter: @prosciuttos
From: Barcelona, Catalonia, Spain

[...]

FR Translator: Thibaud Desodt
Location: Belgium

Media Queries by: Marta Armada (@martuishere) and Javier Usobiaga (@htmlboy)


/* SITE */
Last update:2012/02/04
Language:  [...] / Russian / Chinese
Doctype:HTML5
IDE: Sublime Text, Notepad++, FileZilla, Photoshop

I snipped a lot out, but this follows their own template. Consistency!

Wikipedia

I tried Wikipedia english at http://en.wikipedia.org/humans.txt and was 404'd then redirected to their entry on humans.txt. That's Wikipedia for you.

Google

Google actually has one, but its not really what I expected: text Google is built by a large team of engineers, designers, researchers, robots, and others in many different sites across the globe. It is updated continuously, and built with more tools and technologies than we can shake a stick at. If you'd like to help us out, see google.com/jobs. A job ad :(. I can understand why they can't single out any individuals, lots of hands for google.com.

Flickr

Flickr is the best way to share your life in photos. It's made by a small team of shiny humans, unicorns and pandas. If you'd like to help us, check out flickr.com/jobs.

An advertisement, nonsense and a job ad. This is an anti-humans.txt.

Twitter

No such luck at Twitter, just a 404.

html5boilerplate

This is probably the most common starting template people use to start creating html5 websites. They include humans.txt in the boilerplate:

# humanstxt.org/
# The humans responsible & technology colophon
# TEAM

  <name> -- <role> -- <twitter>

# THANKS

  <name>

# TECHNOLOGY COLOPHON

  HTML5, CSS3
  Normalize.css, jQuery, Modernizr

This is odd for me because on one hand it is great this is included, but on the other hand they structure the section headers differently than the humanstxt.org folks do. It know this is not a big standard or anything, but the actual group pushing this specified almost nothing about the format of the file except the section headers. What is worse is I think these headers are actually better, they look more markdowny and I do think markdown is slowly turning into the oxymoronically plain text format of the future.

Still, I like even my de facto standards to be a little more standard. Even for plain text stuff my inner tech looks at that and says "what if I have to make a parser for that?".

I don't understand the obsession with Twitter in the humans.txt project. Wouldn't facebook, github or just a url for your homepage be as appropriate? Not that you can't put it in there, but all the live examples are Twitter focused.

Github

Github has one, and it looks exactly as you would expect:

/* TEAM */

  Tom Preston-Werner (TPCEO)
  Site: https://github.com/mojombo
  Location: San Francisco

  [...]

  Nikki Everett
  Site: https://github.com/neverett
  Location: 127.0.0.1

Location localhost, cute. This is about as normal as you would expect to see in a humans.txt file. I wonder if they keep it current? Wish they had a bit about the tech in there too.

Other sites

That have no humans.txt file:

Adoption

Not a lot of adoption just yet. As html5 boilerplate gets to power more sites it will hopefully see a better adoption rate.