A more newbie-friendly documentation

After giving a talk on developer experience last week, I was reminded of something that's been bothering me about the Khan Academy developer experience: the documentation.

Previously, our documentation was a one-pager with columns for "Shapes", "Mouse", and other categories. We auto-generated the documentation based on tagged programs, dynamically arranging the columns to balance them and alphabetizing the functions inside each column. It was handy that we auto-generated the docs, because we could add more to the docs without a code change, but it also had its drawbacks:

• The columns weren't always in the same place, so you couldn't memorize the spatial location of what you were looking for.
• Sometimes, the most "advanced" column would be at the top, showing functionality that newbies didn't know yet, and making it harder for them to find what they are looking for.
• On a similar vein, inside each column, the more "advanced" functions would be at the top, burying the more basic, far more commonly used functions (like arc and bezier appearing before rect and ellipse).

Before:

For our audience of mostly beginner programmers, it's important that our documentation be newbie friendly. It should be very easy for them to find what they're looking for, and to not get distracted by things they're not looking for. Given those goals, we've renovated our documentation in the following ways:

• The sections are now ordered in rough "curriculum-order", the order in which students learn things if they go through the tutorials.
• The sections are now rows, not columns, so that the student can process a section before getting distracted by other sections on the side.
• Within a section, the functions are also in curriculum-order, instead of alphabetical. Given we only have ~9 functions per section, it seems better than alphabetical order. If we grow beyond that, we may reconsider.

Now:

At the bottom of the documentation, we used to have links for students to go off and learn programming in other places (including different languages). We now focus that section on links for students to specifically learn more about JavaScript and ProcessingJS, the subjects of the documentation. We've also added a section on the differences between the original ProcessingJS and the Khan Academy version, like disallowing the non-JS Java syntax and making the default angle mode be degrees instead of radians.

If you are using us inside a classroom, you might also be interested in the "cheat sheet" version of the documentation, which I made by simply stripping out all the interface around the documentation panel. You should certainly encourage your students to use the in-page docs, but there are some students that prefer having a paper cheat sheet to look at instead.

We hope these changes will improve the developer experience for budding Khan Academy programmers!