Today Wax’s documentation got a major boost and now has more detailed examples, more API documentation, and more useful text for new users. We hope these improvements will help new users get started with Wax, an open source web mapping stack, and use it to make more interactive and creative maps.

Using Wax’s APIs

The Wax documentation previously included quick examples and a synopsis of each control, and led users to figure out how to use the code from there. This worked well when we had a limited number of controls, but now that Wax has grown we want to show people absolutely everything you can do with the controls. The new Wax Manual is much more thorough, showing off every function and option exposed by the code and providing examples for each on how they can be used.

Wax is the code that we use on our own site builds, every day. It has been battle-tested, and just as importantly designed with a lot of flexibility. Without good docs, this flexibility can be confusing. The new robust documentation make both the code and our concept understandable.

Learn through examples

The Wax manual is filled with examples, just like before, with the little twist that the examples now include all of the HTML that makes them work — everything except for the script tags that include Modest Maps and Wax. This makes it clearer how this code gets on a page, answering the questions of where things go and how the code — which typically includes a reference to a DOM element — relates to the page.

How to make Wax

There’s a section in-progress called how to make Wax, which I think is a big deal. It doesn’t document using Wax — it documents how to make Javascript libraries like Wax and contribute to the project. Wax covers a lot of bases for us, but not everything, so we want people to be able to build to make cool stuff. This document gives the basics of how to write libraries that work well and are testable, documented, and fast. We’ll continue to add to this over the coming weeks.

A lot of the code in Wax is very simple — check out the compactness of something like zoomer.js. This is great — we want small libraries that do things in simple, low-dependency ways that make things work. We’re excited to see what other people come up with once they start building with Wax.

Using the Wax Manual

To quickly get into the nitty and gritty of how this works, the Wax Manual is hosted by GitHub with GitHub Pages. Documentation is written in Markdown, and the site is compiled with Jekyll, which is built into Pages.

You can check out the source code to the documentation in the gh-pages branch of the repository, where you’ll see one small trick — a Javascript function runs all of the code in examples (which are highlighted by pygments), so that the code you see is the code that’s on the page.

Check out the improved Wax Manual, try out Wax, and start contributing.