Monday, May 16, 2011

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.

Friday, May 13, 2011

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:

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).

Wednesday, May 11, 2011

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

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:

Friday, May 6, 2011

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

ToolInput filesInput languageInput commentsOutputWritten in?Examples
Natural DocsIn code or other filesC#, Perl, AS2, partial support for other languages.JavaDoc, or custom "natural syntax"HTMLPerljqPlot, Users list
DoxygenIn code or other filesC++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C#JavaDoc or QT style, with some support for other stylesHTML, TEX, RTF, PS, PDF, ...C++KDE, Users list
doccoIn codeCoffeeScript, JS, Ruby, PythonMarkdownHTMLCoffeeScriptdata.js and drops.coffee
SphinxIn code or other filesPython, C/C++RSTHTML, TEX, PDFPythonPython, Django
DocBookGenerated from XML filesXMLHTML, PDF, CHM, RTF, ...PHPPHP.net

 

Single Language Generators

ToolInput filesInput languageInput commentsOutputWritten in?Examples
JavaDocIn codeJavaJavaDocHTMLJavaAndroid
joDocIn code or other filesJSMarkdownHTMLPerlPhoneGap
JSDoc 3In codeJSJSDocHTMLJava/JSNone yet, in beta.
JSDoc 2 (JsDoc-toolkit)In codeJSJSDocHTMLJava/JSGoogle Maps API v3
JSDuckIn codeJSMarkdown, HTML, some JSDoc tagsHTMLRubyExt-JS 4
ErlDocsIn codeErlangHTMLErlangErlDocs.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.

Thursday, May 5, 2011

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.
jQuery
Django
  • One page for each topic, narrative tutorial-like structure.
  • Generated with RST and Sphinx, More info here.
docs_django
PHP
  • One page for each method, includes examples and comments.
  • Generated with DocBook (XML), More info here.
docs_php
CoffeeScript
  • One page developer's guide with interactive code examples in each section.
CoffeeScript
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.
Twilio
Mozilla Developer Center
  • One page for each topic, includes example code, encourages community edits.
  • Uses wiki/social CMS system, MindTouch
MDC
PhoneGap
  • One page for each class, includes both short and long example code, and a popup feedback widget.
  • Uses joDoc for automated generation.
PhoneGap (Method)
Backbone.js
  • One page for each method (and example code), with framed (but still linkable) navigation.
  • Manually written.
BackboneJS
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.
Yii Framework
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.
NodeJS
Play! Framework
  • Includes step-by-step tutorial and developer's guide (no reference).
Play! Framework
Sencha ExtJS
  • One page for each class, highly linked, inline code examples, and search with auto-complete.
  • Generated using JSDuck and Markdown.
Sencha
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.
SimpleGeo
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.
Twitter
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.
Android

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.
Python
Facebook
  • A mix of reference style docs, articles, and github-hosted readmes. Includes search and (Facebook) comments. Complaints: too loosely organized.
Facebook

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.
Ruby
Amazon Products API
  • Frameset docs, both tutorial and reference style. Complaints: takes many clicks to find the reference, provided sample code does not work.
Amazon
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.
Paypal
OpenLayers
  • Wiki and reference. Complaints: No code examples, hard to find docs.
  • Generated using NaturalDocs.
OpenLayers
CouchDB
  • Wiki with articles by topic. Complaints: Hard to navigate.
  • Uses the MoinMoin wiki engine.
CouchDB

.