Prerelease of Zajal's New Documentation

The content is incomplete, broken even, and the styling hasn’t even begun, but this is the first honest-to-goodness spat-out-from-the-source preview of Zajal’s new documentation!

Why does this matter? Zajal’s old original documentation was very incomplete, and used a barely customized form of YARD’s default theme. In short, it was unusable. Then the server crashed and I replaced it with an even more terrible thing that was intended as a placeholder, but stuck around for far too long.

Without proper documentation, there may as well be no language. This had plagued me for a while, and the docs have been a major goal of my time at Eyebeam. Thursday’s workshop is the perfect deadline to get this up and running.

To streamline as much as possible, I use the fantastic YARD to parse my source code and and comments generate. The first two documentation attempts use YARD’s built in theming engine, which I found frustrating to use and customize. Fortunately, it’s a very well architected library, and I was able to cook up my own templating solution based on Mustache without losing any of YARD’s power. Mustache is much easier for me and my designer to work with.

The screenshots in the examples are generated live from the example code, base64 encoded, then embedded into the HTML! I don’t know why, but that excites me!

I plan on spending the next few days actually writing the documentation (how about that?) and built in examples for the workshop. Haitham is helping because he is an amazing human being and has a suspiciously similar domain name to mine.

I’ve been thinking of ways to get people involved in generating documentation and examples. One idea I had was to set up a twitter account where that you can tweet Zajal code at, and it will reply with a 100x100 rendering of the output, just like in the documentation. I can pick the best/most retweeted ones to use in the app or the docs. How does that sound? Any other ideas?

As always, this project runs on feedback. Let me know what you think!

Q:Have you considered building a simple editor into the app akin to the Processing app?

Anonymous

My plan is to hack an existing open source code editor into a Zajal specific one.

One of Zajal’s features is that it doesn’t concern itself with editors (it just watches files for changes) and as a result allows you to use whatever you want to write code. This is great for advanced coders who can’t live without their preferred editor. For people who don’t have such a strong preference, Zajal will be bundled with an easy to use editor that it uses by default. Everyone wins!

A month ago, I was awarded a fellowship at the Eyebeam Art + Technology Center in New York. The broad theme of my fellowship is programming language design, but the primary project will be Zajal! Here are some notes about what I hope my time here will bring. Better Blogging I’m making it a goal to document the process of developing the language better through this blog. So, for those of you curious how these things get built, stay tuned! Next Steps To take the project forward, two things have to happen: In the short term, the current branch needs to be made generally usable by stabilizing it, rounding it off, and improving documentation. This will culminate in Zajal 0.3.4. In the long term, Zajal needs to be rewritten from the ground up for it to fulfill it potential. This will culminate in Zajal 0.4. Finishing the current branch is important, because a rewrite will take time and I want to start user testing as soon as possible. Rewriting is important because the current codebase, has become very difficult to build on, and exciting features like iOS support and true Ruby Gems integration will only be possible by starting over. All the lessons learned from previous Zajal versions will direct the implementation of the new codebase. Work on both fronts will start immediately and progress in parallel, with more emphasis placed on the current branch initially. Better Instruction Zajal’s biggest problem, in my opinion, is that not enough effort has been made to make it easy to get into. Efforts to correct this will include better, more consistent documentation, and tons more built in examples that are specific to topics of functionality. Hack Sessions and Workshops I plan to use the space at Eyebeam to hold hack sessions, game jams, workshops, and other coding events. I’ll be posting dates on this blog. If you’re in New York, stop by! Crazy Ideas No promises, but this is what’s been on my mind Mobile Support The architecture I have in mind for iOS/Android support is really exciting. I’m imagining a Zajal app you would get off the App store for your device. When launched, this app would make itself visible on the local wifi network. The Zajal interpreter running on your computer will check for any devices on the network, and push any code changes it picks up to them. So, you’ll be able to code as normal, and Zajal will push your changes over the network to any listening devices! The app will store any sketch it receives, so it can relaunch them later without need for a computer. So, you’ll be building a portable sketchbook as you go! Awesome! Browser Support This is a long way off, but through godless unholy trickery, it is technically possible to compile Ruby code into JavaScript and run it in a browser. Precedents include HotRuby and Emscripten. Seriously, though, here be dragons. A lot of people have asked for this, so I’m looking for the most efficient way to pull it off. My main concern is having to reimplement large portions of openFrameworks in HTML 5. Gems and Bundles The Ruby language is used for very high profile projects on the web, so the community has developed all sorts of exciting technologies to share and deploy code. Zajal plans to leverage Ruby Gems to reusable share code and Bundler to share complete sketches. How this will work is not clear yet, but the idea is to move beyond the days of manually copying files into folders and hoping things will work.
Pop-upView Separately

A month ago, I was awarded a fellowship at the Eyebeam Art + Technology Center in New York. The broad theme of my fellowship is programming language design, but the primary project will be Zajal! Here are some notes about what I hope my time here will bring.

Better Blogging

I’m making it a goal to document the process of developing the language better through this blog. So, for those of you curious how these things get built, stay tuned!

Next Steps

To take the project forward, two things have to happen:

  1. In the short term, the current branch needs to be made generally usable by stabilizing it, rounding it off, and improving documentation. This will culminate in Zajal 0.3.4.
  2. In the long term, Zajal needs to be rewritten from the ground up for it to fulfill it potential. This will culminate in Zajal 0.4.

Finishing the current branch is important, because a rewrite will take time and I want to start user testing as soon as possible. Rewriting is important because the current codebase, has become very difficult to build on, and exciting features like iOS support and true Ruby Gems integration will only be possible by starting over. All the lessons learned from previous Zajal versions will direct the implementation of the new codebase.

Work on both fronts will start immediately and progress in parallel, with more emphasis placed on the current branch initially.

Better Instruction

Zajal’s biggest problem, in my opinion, is that not enough effort has been made to make it easy to get into. Efforts to correct this will include better, more consistent documentation, and tons more built in examples that are specific to topics of functionality.

Hack Sessions and Workshops

I plan to use the space at Eyebeam to hold hack sessions, game jams, workshops, and other coding events. I’ll be posting dates on this blog. If you’re in New York, stop by!

Crazy Ideas

No promises, but this is what’s been on my mind

Mobile Support

The architecture I have in mind for iOS/Android support is really exciting. I’m imagining a Zajal app you would get off the App store for your device. When launched, this app would make itself visible on the local wifi network. The Zajal interpreter running on your computer will check for any devices on the network, and push any code changes it picks up to them. So, you’ll be able to code as normal, and Zajal will push your changes over the network to any listening devices! The app will store any sketch it receives, so it can relaunch them later without need for a computer. So, you’ll be building a portable sketchbook as you go! Awesome!

Browser Support

This is a long way off, but through godless unholy trickery, it is technically possible to compile Ruby code into JavaScript and run it in a browser. Precedents include HotRuby and Emscripten. Seriously, though, here be dragons. A lot of people have asked for this, so I’m looking for the most efficient way to pull it off. My main concern is having to reimplement large portions of openFrameworks in HTML 5.

Gems and Bundles

The Ruby language is used for very high profile projects on the web, so the community has developed all sorts of exciting technologies to share and deploy code. Zajal plans to leverage Ruby Gems to reusable share code and Bundler to share complete sketches. How this will work is not clear yet, but the idea is to move beyond the days of manually copying files into folders and hoping things will work.