So, what am I, exactly?

Lately I have struggled to find a good answer to the question "So, what are you?". When I was a kid, nobody asked me that - I was just a kid. At the most, they'd ask me what grade I was in, and that was easy. Then, in my first (and only) job at Google, when people asked me that, I could answer with my job title. But now that I'm not a kid or a Google employee, I'm not quite sure what I am.

My standard response has been "web developer." I do web development, I go to all the web development events, and all the people I helped as a Googler were web developers. But I'm not convinced, and I become less convinced the more I am approached by people looking for "web developers" thinking that I fit the bill. I know this doesn't bode well for my job opportunities in the future, but I don't think I'm actually a "web developer", at least not the kind they are looking for.

See, when I do web development, I do it because it is the best way that I know to turn an idea into something tangible; I don't do it purely for the joy of programming. I don't dream of spending all day coding, I dream instead of making things that I enjoy, and maybe a few others too. In fact, I don't think I would be happy spending all day programming for months on end; I like too many other aspects of making things. I want to write about them, I want to brainstorm them, I want to tell the world about them. I want to spend equal parts of my life using the different parts of my brain, and I want to be able to share creations with the world as a result of that synergy.

Why does it matter what I am, anyway? Well, first, I need an answer for all the people that I meet now, who want to be able to fit me into a nice bucket in their head. But, second, I need to figure out what I'm doing next in life. If I am a web developer, then I should probably join a new company, learn more web skills, and increase my knowledge there. But if I am not - and I suspect as much - maybe I should be picking a different path. I have done many side projects, and now it might be time for me to pick an idea and make it my main project, to see how far I can take it and how many people I can share it with. Or, put in the more usual terms of today's web world, perhaps I should become a (co-)founder.

I am not 100% sure of this - part of me is worried that I don't have the focus to pick one idea and stay with it, part of me is worried that I'll pick the wrong idea, and part of me is worried that I'm not business-oriented enough to make something profitable. But the other part of me thinks that I should find out or I risk spending the rest of my life wondering.

Reading My Way to Better Design

I realized recently that I am completely capable of coding up a website frontend, but I struggle to make that website frontend look really good. My webdesign tends to be either too simple (“austere” is how one observer described it) or too tacky (my love for everything 80s seeps into all parts of my life). I was okay with this before when I was just making developer-facing demos, but now I’m at a stage where I want to make user-facing webapps, and I want the users to experience them and think “Wow, slick.”

So, I’ve set out to acquire a better taste in design, and I decided one way to do that is to surround myself on a daily basis with examples of great design. After Google’ing around and reading this HackerNews thread, I set up a folder in my Google Reader of 10 design-related blogs, and I now spend every morning reading through the posts (after drooling over my recipes feed, of course). It’s a great mix of topics, ranging from web design how-tos to well-designed physical products. It's hard for me to quantify if my design skills are improving, but I am at least thinking much more about it than before and acknowledging its importance.

If you want to do the same as me, you can subscribe to my folder feed or subscribe to the individual blogs listed below:

• A List Apart (RSS)
• Brain Pickings (RSS)
• I love typography (RSS)
• Logo Design Love (RSS)
• Noisy Decent Graphics (RSS)
• Smashing Magazine (RSS)
• swissmiss (RSS)
• UI-patterns.com (RSS)
• UX Movement (RSS)

Please let me know in the comments if you have other suggestions for great blogs to read (and books too, while you’re at it).

No, Really, I'm Shy: My Ignite I/O Talk

Update: I've now created a site with all my tips for event attendees and organizers that grapple with shyness. Check it out at ProjectIcebreak.com

As many of you know, I'm kind of an Ignite junkie. I love the format - 5 minutes, 20 slides, 15 seconds auto-advance - and I love that I can use that format to talk about topics that I can't fill a whole hour with. At this year's Google I/O 2011 Ignite show, I got to give a talk on something that I think about a lot: my shyness. Most people don't believe me when I tell I am actually quite shy at my core, and so I dedicated my five minutes to explaining what shyness is to me and how I workaround it. The talk went well, and multiple folks approached me afterwards about their own shyness and hacks around it. Mission accomplished!
You can watch the video on Youtube - I'm at 24:09:

And/or you can read the slides on Slideshare:

No, Really, I'm Shy

Roundup: Developer Documentation Generators

While researching what developers love about their favorite API documentation sets for my last post, I also investigated what tools the API teams use to generate the documentation. Some teams just hand-write HTML, but most use code-based generators for the references and/or some sort of markdown for writing the guides. A good tool or toolset should make it easy to update the reference for every API release (outdated documentation should be avoided at all costs) and painless to write documentation about how to use the API (writing is one of those tasks that people put off - the less obstacles there are, the better). Based on my experience, here are the questions you should be asking when picking a tool:

• What is the input for the tool?
  • Does it run over code and/or supplementary files? It's great to use a tool to automate your reference generation, but even better if you can use the same tool to write your developer's guide as well.
  • What languages will it process? If your API is written in multiple languages (like Flurry, the company I did this research for), you probably want to pick a tool that will work over all of them so you can have a consistent process and output.
  • What style of comments does it parse? If you're already using comments to instruct your compiler, you won't want to use a different format just for the docs.
• What is the output for the tool? HTML is a must, even better if it can do multi-page and single-page. PDF and other formats can also be quite useful.
• What is it written in? It needs to work in your development environment, and ideally hook into your build system.
• How easy is it to customize for your needs? The ideal tool includes easy customization options that don't require digging into the code, but is also open-source in case they don't do it for you.

To give you an idea of (just a fraction of) what's out there, here is a breakdown of the documentation tools used by the APIs from the last post.

 

Multi-Language Generators

Tool	Input files	Input language	Input comments	Output	Written in?	Examples
Natural Docs	In code or other files	C#, Perl, AS2, partial support for other languages.	JavaDoc, or custom "natural syntax"	HTML	Perl	jqPlot, Users list
Doxygen	In code or other files	C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C#	JavaDoc or QT style, with some support for other styles	HTML, TEX, RTF, PS, PDF, ...	C++	KDE, Users list
docco	In code	CoffeeScript, JS, Ruby, Python	Markdown	HTML	CoffeeScript	data.js and drops.coffee
Sphinx	In code or other files	Python, C/C++	RST	HTML, TEX, PDF	Python	Python, Django
DocBook	Generated from XML files	XML		HTML, PDF, CHM, RTF, ...	PHP	PHP.net

 

Single Language Generators

Tool	Input files	Input language	Input comments	Output	Written in?	Examples
JavaDoc	In code	Java	JavaDoc	HTML	Java	Android
joDoc	In code or other files	JS	Markdown	HTML	Perl	PhoneGap
JSDoc 3	In code	JS	JSDoc	HTML	Java/JS	None yet, in beta.
JSDoc 2 (JsDoc-toolkit)	In code	JS	JSDoc	HTML	Java/JS	Google Maps API v3
JSDuck	In code	JS	Markdown, HTML, some JSDoc tags	HTML	Ruby	Ext-JS 4
ErlDocs	In code	Erlang		HTML	Erlang	ErlDocs.com

 

If you're interested in exploring tools further, check out the Documentation Generators section of my Developer Support handbook and this nearly comprehensive comparison of documentation generators from Wikipedia. There are always new tools being built out there by developers not quite satisfied by the current offerings and going at it their own way - and that's a great thing for all of us.

Let me know in the comments what tools you use (or are building yourself!) and your experience with them.

Roundup: The Best Developer Docs

As I mentioned in my previous post on "What makes a good Developer Experience?", I'm currently consulting with Flurry to advise them on improving their developer experience. They're starting with a revamp of their documentation and API reference. Per what I wrote in the Documentation chapter from the Developer Support Handbook, good documentation should include tutorial style content, an API reference, and sample code, and should be fully linkable and searchable.

To confirm that my criteria for good docs aligns with what developers in the wild think, I conducted an informal survey on Twitter asking developers for their favorite and least favorite docs. I reviewed their picks, and as I guessed, here's what was common amongst the favorites:

• Easy navigation: everything linked, clear table of contents, every page just takes 1-2 clicks to get to. Example: Yii.
• Easy search:. prominent search box with autocomplete for method/class names. Example: Sencha.
• Reference *and* guide: most offer both a technical breakdown of every part of the API (the reference) as well as a step-by-step narrative guide for using the API. Example: Twilio.
• Inline code samples: in the reference, every class/method comes with example code below the definition, and sometimes that code can even be run in the browser. (Or for HTTP APIs, sample request and responses in every data format are offered). Example: CoffeeScript.
• Comments: a threaded comment system on every page, for developers to discuss issues or usage. Example: jQuery.

And here are some cool bonus features from the favorites (that may not work for everyone):

• Community edits: The Mozilla Developer Center lets anyone login and edit the information themselves.
• Feedback loop: The PhoneGap docs prompt the developers to give them feedback on every page, and they use that to improve the docs.

Many of the favorites are written by the engineers themselves, which likely keeps them more up to date and accurate (and proves that engineers can write!).

The least favorite documentation sets typically suffer from basic usability issues, like lack of search or deep links. When you're writing documentation, you need to remember that your developers won't benefit from it unless they can find it - searchability and linkability should be a top priority.

I've rounded up the documentation sets in the tables below, with links, short description (including how they were generated, if known), and a thumbnail. I've also embedded a slideshow of the screenshots. Feel free to comment with your own opinions on what makes for a great set of developer docs!

Screenshots

Rave Reviews

Ordered by popularity, these documentation sets received all positive reviews. Great work!

jQuery	One page for each method. Includes code examples and discussion. Manually written.
Django	One page for each topic, narrative tutorial-like structure. Generated with RST and Sphinx, More info here.
PHP	One page for each method, includes examples and comments. Generated with DocBook (XML), More info here.
CoffeeScript	One page developer's guide with interactive code examples in each section.
Twilio	One page for each topic, includes example requests and responses for REST API and example XML for XML API. Manually written by the engineers.
Mozilla Developer Center	One page for each topic, includes example code, encourages community edits. Uses wiki/social CMS system, MindTouch
PhoneGap	One page for each class, includes both short and long example code, and a popup feedback widget. Uses joDoc for automated generation.
Backbone.js	One page for each method (and example code), with framed (but still linkable) navigation. Manually written.
Yii	One page for each class, lots of internal linking, prominent search with autocomplete. Includes code samples and links to original source code. Generated with custom, open-source PHP tool.
NodeJS	One page for each topic, or can be viewed all on one single page. Includes code examples for each method. Generated using doctool and Markdown.
Play! Framework	Includes step-by-step tutorial and developer's guide (no reference).
Sencha ExtJS	One page for each class, highly linked, inline code examples, and search with auto-complete. Generated using JSDuck and Markdown.
SimpleGeo	Organized by topic with one page for each. Written in a narrative form and includes code examples. Generated using Django and templates, More info here.
Twitter	One page for each API endpoint ("resource"), with example request and responses in XML/ATOM/JSON. Partially generated from code, manually curated by engineers.
Android	Javadoc style, with ability to change language and API level, plus search with auto-complete. Incudes tutorial style articles as well. Generated from code using JavaDoc.

Mixed Reviews

These documentation sets had both positive and negative reviews. (What works for one developer doesn't always work for another).

Python	One page for each topic, with embedded references and code examples. Complaints: no search/comments. Generated using Sphinx and RST.
Facebook	A mix of reference style docs, articles, and github-hosted readmes. Includes search and (Facebook) comments. Complaints: too loosely organized.

Not-So-Great Reviews

These documentation sets had all negative reviews. (Well, they can always improve!)

Ruby	Javadoc style with framesets. Complaints: can't be searched or linked, no per-topic organization. Generated from code using RDoc.
Amazon Products API	Frameset docs, both tutorial and reference style. Complaints: takes many clicks to find the reference, provided sample code does not work.
Paypal	Includes articles and reference docs. Complaints: instructions are dumbed down, deprecated information isn't marked as such, there are too many places to find a piece of information, not enough example code.
OpenLayers	Wiki and reference. Complaints: No code examples, hard to find docs. Generated using NaturalDocs.
CouchDB	Wiki with articles by topic. Complaints: Hard to navigate. Uses the MoinMoin wiki engine.