Thursday, January 2, 2014

New Year, New Documentation

We're starting off the New Year with another overhaul of our documentation, and we're pretty excited about it. Here's a round-up of the major improvements that we've made based on the feedback from our fantastic community of learners and teachers:

We documented everything. We previously linked to the ProcessingJS reference for the less commonly used functions, but that is a confusing reference for Khan Academy programmers due to their use of Java syntax and references to renderers that we don't support. We went through the entire ProcessingJS reference to find everything that we do support but hadn't documented yet, and added them to our docs. That meant adding a few new sections entirely (like Transforms and Time & Date) and adding a "See also" to existing sections. If we're missing something still, please let us know. Our goal is that you should be able to learn about everything we support from ProcessingJS from our own documentation.

We added visuals. We get many questions from new programmers about how to draw particular shapes. To help them figure that out faster, we've added screenshots to the "Shapes" section and the new "Complex Shapes" section. Now they can look at a glance to see what shape looks the most like what they have in their head, without having to know already what a "bezier" curve is.

We introduced a consistent format. Now, for everything we document, we follow the same structure: a description followed by a table of parameters and parameter descriptions. This is based on the ProcessingJS reference, but is also based on documentation that learners will find when using many programming languages and libraries. We hope that the more consistent format will help them learn how to use our documentation better, and also to use others' documentation.

We improved the linkability. We made the links on the documentation look more like links, and we also added in-page anchors with a "Quick jump" at the top of the page.

We made it translatable. Previously, we documented functions and parameters inside the comments of the demo programs, but since we don't yet have a translation mechanism for comments, that meant that our documentation had to be in English for everyone. Now, we've moved the descriptions into a field in our database, which will send it off to CrowdIn for translation, which means we could have a Spanish-language documentation! (If you can help with that, read this post.)

We differentiate ProcessingJS from JS. We get a lot of confusion from students about which parts of what they're learning is from JavaScript and which parts are from ProcessingJS. To try and reduce that confusion, we added headers in the docs for "ProcessingJS" and JavaScript.

Check out the new and improved documentation, and let us know what you think… and encourage your students to use it, of course!

No comments:

Post a Comment