Over the last few years, we’ve seen more and more open source projects transition to a Creative Commons license for their documentation. Specifically, most projects tend to use some version of CC-BY-SA. There are some projects that use a permissive code license like Apache or MIT for documentation, and certainly still some that use the GFDL. But for the most part, the trend has been toward CC-BY-SA.

This is a good thing. Creative Commons has been at the forefront of the open culture movement, which has had just as profound of an impact on our lives as the free software and open source movements before it. Using a Creative Commons license means that documentation writers have access to a wealth of CC-licensed images and videos and audio files. We can reuse icons and other imagery when creating network diagrams. We can use background music in our video demonstrations. And because so many projects are moving toward Creative Commons, we can all share each other’s work.

Sharing work is a two-way street if we all use the same license. If somebody uses a non-sharealike license, others can reuse their content, but they can’t reuse content from projects that use sharealike. So there’s a lot of network value to having everybody use CC-BY-SA.

But CC-BY-SA shares one serious flaw with the GFDL: Any code samples contained in the developer documentation is also licensed under the same license. This is true of any license, even permissive licenses like Apache or MIT, but with a copyleft licenses like CC-BY-SA or GFDL, it means the code can only be used in software projects under that same license. Of course, nobody writes code under CC-BY-SA or GFDL, so this presents a big problem.

We want people to be able to reuse code samples. That’s why we provide them. And we want to place as few barriers as possible to reusing them. Any sufficiently small code sample isn’t worth worrying about, but where’s the cutoff? Are the code samples in the Save Window State Howto sufficiently small? I don’t know. I’m not a lawyer. This is something we struggled with in GNOME, and it’s something other projects have realized is a problem as well. It recently came up on the OpenStack documentation mailing list, for example.

You can always put an exception on your license. You have a few choices. You could explicitly license your code samples under a permissive code license, or even CC0. GNOME has a standard license exception that reads “As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this documentation under the terms of your choosing, without restriction.” This came from an honest-to-goodness lawyer, so I hope it’s OK.

But this still has a problem. GNOME is no longer using a stock Creative Commons license. Neither is anybody providing an exception to put code samples under a permissive code license. This means that two-way sharing is no longer a viable option. Anybody can take GNOME documentation and reuse it, even effectively uplicensing the code samples to CC-BY-SA. And GNOME can take any non-code prose from other CC-BY-SA content. But GNOME cannot reuse code samples from any project that doesn’t carry a compatible exception.

I’ve seen this in enough projects that I think it’s something Creative Commons should address directly. If there were a standard CC-BY-SA-CODE license that included a stock permissive exception for code samples, we could all switch to that and recommence sharing our developer documentation. Who can help make this happen?

6 Responses to “Creative Commons for Developer Docs”

  1. Jon Nordby Says:

    CC-BY the docs, specify that example code be attributed with a link back to the URL as a code comment (things which are not examples can have a “stricter” attribution)? Such a comment is often useful to the devs, which can look up later and compare the now-potentially-changed code against the now-potentially-updated example. The comment with URL can even be included into the docs itself, for ease of compliance (copy/pasting will automatically include it).

    • shaunm Says:

      The trouble with dropping SA is that you lock yourself out of a lot of content that’s under SA. Also, every docs person I’ve talked to about this doesn’t even care about attribution for using their code samples.

      There’s an added twist in that it’s not clear what constitutes sufficient attribution. Is a code comment enough, or do you need to be attributed in a place that users see? This is more pronounced with proprietary software, where users couldn’t even in theory see the attribution by browsing your source.

      • Jon Nordby Says:

        Not being able to use SA content is fair point*, especially since both Wikipedia and Stack Overflow uses CC-BY-SA. Which makes me think that they would be very interested in the problem/solution too.

        * though these days I’m mostly of the opinion that viral licenses are not worth the hassle and one should just go liberal.

  2. Jon Nordby Says:

    Having the link there also allows in case of open projects to track which projects are using certain pieces of example code.

  3. Gez Says:

    Can’t you just move the code samples to a different file licensed with a suitable license?
    You can add links to your CC-BY-SA documentation poiting to wherever the code samples are stored and that should be enough to avoid the licensing conflict.

  4. shaunm Says:

    We don’t want to hurt the reader experience by making them switch between different files just because of legal loopholes. Besides, that doesn’t solve anything. We can already put the code samples under a different license. We can do it with a blanket exception in our license notice, or we can do per-sample exceptions as captions near the code.

    The point is not that you can’t license code samples differently than prose. The point is (1) that you should, and (2) that there’s value in all of us deciding to do it the same way.


Comments are closed.