Tuesday, January 19, 2010

On language documentation for experienced programmers

For someone familiar with programming it's pretty easy to get going with a new language.  The new language will likely contain many familiar concepts, just perhaps done a bit differently.  There are stylistic differences between languages, but I'm talking about the basics here. 

What is the most efficient way to present these programmers with what they need to know to get going with a new language?

I tend to find most documentation isn't that good for this task. What I find useful is concrete examples of the features, directly showing the syntax and the results you get for particular inputs. 

Like if I already know how to do regular expressions and want to see how they're done in Python, I just want to see what a call looks like in Phython and see things like what sort of value is returned if there is no match.   

So perhaps you could have documentation that was essentially a representative bunch of simple examples showing the exact inputs and exact outputs.

You'd have clusters of examples showing the different variations on a particular construct or function. Eg those showing the syntax for doing diffferent things with regular expressions. They'd come with brief descriptions of what is being illustrated. Eg 'non-greedy matches'. 

It'd be even better of you could edit the examples then and there to modify the input values and see how it effected the results.  

The idea would be to have the information in a format that is concise and easy to scan, to make it as quick as possible to lookup what you want to do.   

No comments:

Post a Comment