I forgot to mention the GTK+ UVC Viewer, which is what I used to record using the webcam on Ubuntu. It was excellent.

With Kaltura (open source version), you can host it on their CDN, or host it yourself. It seems like that is pretty flexible.

From watching it once, I see that I should probably talk slower. Mostly the video seemed in-sync with the audio. What did you think about the quality and/or the idea?

Original article: Open Source for Retired People

It seems that their goal is to improve the documentation of free software products to increase their adoption. You can check this out on the about tab. The discussion on their FLOSS manuals overview reminded me of thoughts that I was having about having some sort of open source documentation or tech writing business. They basically outline the major models for producing content and being compensated for it. There were several sections that focused on the prevailing mindset, technologies, and economics of doing open source (in this case, for free software) documentation. I agree with them that adequate and consistent documentation is something that keeps most open source and free software from being widely adopted on the desktop.

There have been some free software products out there that have been very widely accepted, such as Firefox. I wonder if it is because the program itself was leaps ahead of the proprietary alternative, or if something else contributed to its success.

Original article: Free Software Documentation

I would go so far as to say that there should be open source technical writers. They look for interesting projects to write basic documentation for. While there are a smattering of tutorials for certain frameworks, they are not condensed, are not authoritative, and are often misleading because of changes to the framework or convoluted examples. When the core developers move at the speed of the forum or even IRC, it’s tough for a new person to have anywhere near that amount of knowledge. A centralized wiki with pertinent and up-to-date examples is quite useful.

If you are not yet a badass developer, this kind of project aids you in three ways. First, you gain experience looking at unfamiliar code bases and reasoning about them. This is especially helpful if you maintain code, and also assists you in writing more maintainable code. Second, you get some street cred for being closely involved with the developers on the project and working with them. You’re likely to learn something from the alpha geeks and advance your skills. Third, your writing skills improve, which helps you out in many areas over the long run.

In a nutshell, the kind of people who are building their own system or framework are generally not obsessed with documenting for average people. This could be due to time constraints or general personality traits. But the value that they create is wasted if people are not comfortable interacting with it.

Clojure

There is an interesting thread on the Clojure discussion group about making examples readable and general ways to help developers who are new to the language and want to code idiomatically. One post mentioned the Clojure page on concurrency. If you can read through the example code there and want to tackle concurrency (which is supposed to be a strength of Clojure), then I applaud you. This isn’t a knock against Clojure, it’s just so new that most everyone who’s interested has been playing around with it and trying to understand it better.

One of the most important points in the post is that to get a community rallied around a language or framework, it’s necessary to have good documentation so people aren’t put off by it. The Clojure folks are getting there, as there are a couple of wikis around that people dump stuff into.

qooxdoo

The qooxdoo framework illustrates one of my favorite examples of excellent open source documentation. When I first started looking at it, I was impressed by the amount of examples, pictures, screenshots that were included. The manual is rife with examples and code snippets.

They have a huge demo area that shows how simple effects can be created using at it. Looking at these demos, I started visualizing about how exciting it would be to work with this framework. As another great demo, it has an API documentation viewer, which itself is written with qooxdoo. It must have taken time to generate all of this…

Parting thoughts

On the other hand, one could argue that with a nascent open-source product, having too many people involved early is problematic for direction and quality density. Also, the people who create code which uses the product will constantly have to change their code because the underlying architecture or best practices change. It’s the bleeding part of the bleeding edge.

I’m not saying that I’m committing to doing any of this… Just thought that this was an interesting line of thinking.

Original article: Open Source Tech Writer

One thing that has piqued my interest of late is theories in JUnit 4.4+.

Overview

In JUnit, the still experimental theory functionality is derived from the open-source Popper project. The name comes from Karl Popper’s work on the philosophy of science. He was a major proponent of saying that something isn’t scientific unless it is falsifiable, and that theories cannot be proven correct, merely shown to have exceptions. If someone can provide an exception, it means that the theory does not match all of our observations. Theories are models of the world, so while a model may not be correct, it can still be useful.

So what are theories in software good for? When using test-driven development, the tests serve as a form of code documentation. However, there are certain properties of code that are known or assumed by the developers that are difficult to codify as simple tests. Theories provide a simple and expressive means for at least the following cases:

For example, you might have a theory that data that is serialized into XML and then unserialized should always result in the original object. This seems to make sense, but it might be time-consuming or error-prone to specify all of the different tests that you have to consider. A single theory can codify this assumption.

In JUnit, theories are a special case of parameterized test. So instead of using the standard test that has no parameters, you add parameters to make testing various combinations of values shorter and easier. You can then take these parameterized tests further by specifying data points to test for by default in an expressive manner.

Example

Alright enough theory. What does a JUnit theory actually look like? Given that you have a theory about two methods on a Currency object that should be inverses of each other, one nice example is:

    @Theory public void multiplyIsInverseOfDivide(
            @TestedOn(ints={0, 5, 10}) int amount,
            @TestedOn(ints={1, 2, 3})  int multiplier) {
        assertThat(new Currency(amount).times(multiplier).divideBy(multiplier).getAmount(), is(amount));
    }

On the first line, we declare that we are going to postulate a theory, and give it a unique name. This method would typically live in a test suite or test file of some sort. The next two lines are the parameters to the test method. The parameters are prefixed by annotations to put in sample test values. All permutations of these values will be attempted when running the theory, and the values will be reported for any failures so we know what happened when the theory failed. On the last line, we test that the functions are indeed inverses by invoking them and making sure that the original value is the same as the end value.

Going further

So big deal, we could easily just create a helper test method that does something similar and we could pass whatever values to the method that we wanted. Well, hold on a second. One thing I haven’t mentioned yet is that there are some nifty tools that support automatically inserting values in to test theories. The tools automate searching the theory space for members that fit the theory assumptions but cause the theory to fail. Something like this might be useful in detecting an off-by-one error or corner case that you hadn’t considered while implementing. Typically for development you would just run the test cases presented with the method, and then would search the theory parameter space with spare cycles. This enables you to have great power as well as having blazing unit tests, which is key for any test-driven development.

If we allow automated searching of the theory space, there is one small problem with the example theory listed above. Can you see it?

The assert attempts to multiply by the multiplier and then divide by the multiplier, so a zero value for the multiplier will cause a divide by zero error. When we use automated tools for searching the theory space, we want to say that this theory only holds when the multiplier is not zero. We can easily do this:

    @Theory public void multiplyIsInverseOfDivide(
            @TestedOn(ints={0, 5, 10}) int amount,
            @TestedOn(ints={1, 2, 3})  int multiplier) {
        assumeThat(multiplier, not(0));
        assertThat(new Currency(amount).times(multiplier).divideBy(multiplier).getAmount(), is(amount));
    }

Similar expressions exist for ensuring the value is positive, and so forth. You might create a different test or theory to show the expected behavior when the multiplier is zero.

I really liked the use of Java annotations to make this code considerably more readable. You would probably need a runner of some sort to specify the values if you didn’t do it right there in the method signature.

It seems like there is some overlap between theories and contracts, but I won’t go into that at this time. Theories exert positive design pressures like tests do, in that they tend to lead to leaner code that just does what the theory asks for.

Extensions

In Ruby on Rails, it would be nice to be able to easily test methods with multiple models that you have defined. For example, you might have a theory:

  fixtures :users

  def test_admin_user_can_access_this_page
    login(users(:admin_user_1))
    get :this_page
    assert_response :success
  end

  # the previous test, but better
  def theory_that_admin_users_can_access_this_page(User user)
    assume(user.is_a? AdminUser)
    login(user)
    get :this_page
    assert_response :success
  end

So, instead of using just one user or manually going through a set of users, you could just specify a whole bunch of fixtures and go to town. This might make fixtures less brittle by pointing out subtle interactions between parameters that would cause the theory to fail. I’m not sure how the syntax would look, and I’m not sure how you could use something better than annotations in Ruby.

Another thing that might be nice would be to say: I have a theory that any strings we put to the page from the database will always be escaped. The automated theory explorer could step through the pages that you define and try once with some basic data and then start generating HTML and JavaScript garbage and ensure that nothing gets through to the users. This might be a nice way of preventing cross-site scripting attacks (although I would imagine that there are tools that already exist for just this purpose.)

I looked, but could not find a Ruby plugin to handle theories. Hmmm…

Further reading

Some excellent resources are:
The Popper tutorial
A great paper with examples of use and benefits (see the pdf on that page)
General overview of Theories in JUnit [pdf]

Original article: Introduction to Theories