After thinking about my last post and poking around Google Code i came up with a plan. I want to improve the documentation of libgdx, by a lot. The Javadocs are not horrible per se, but Javadocs (without package html) are usually only good for reference and don’t answer more high-level questions. I thus want to propose the crowd-sourced libgdx documentation initiative. Here’s how that works.

Everyone becomes a Contributor!

Everyone will be capable of contributing to both the development guide/wiki as well as the javadocs. The first thing you need to do is drop me an e-mail at contact at badlogicgames dot com. Provide a valid Google account so i can add you as a contributor to libgdx on Google Code. You will be granted write permissions for the Wiki only. If you want to also contribute to Javadocs, follow the instructions below.

Next decide on what you want to work on.

Development Guide/Wiki

The wiki/development guide is currently a work in process. As you can see there’s already an outline of which topics it should cover. Check out what’s there so far to get a feel for how individual dev-guide articles should look like. Then pick one of the items and create the article for it. In general you want to give an overview of a feature, provide info on differences between platforms if any, and show a few code snippets demonstrating the usage of the feature.

The second type of wiki contributions are articles. An article illustrates a complete working example for some specific functionality, e.g. wrapping 3rd party services. You can chose to embed your code in the article and refer to the project setup article for the project creation step.

Java Docs

While libgdx’s javadocs are comparatively complete, some parts might be outdated or badly written (or actually missing). Fork libgdx on Github, load up the Java files you want to improve, push the changes back to Github and send a pull request. Please only improve on the Javadocs, do not manipulate the code itself. I’ll merge all pull requests manually, don’t try to trick me This guide shows you how to write proper Javadocs (more or less).

The best way to identify underdocumented class is to check out the online Javadocs. Browse through the classes and if anything seems bad, fire up your IDE/editor, edit the docs, commit and push. To lower merge burden, please batch up your commits into a single pull request.

What about the User Wiki?

The user wiki effort has died down somewhere around september. None of the development team ever maintained any portions of it, so it was a very undirected effort. With the outline of the TOC and articles already written as well as our commitment to curate additions by users, it is my hope that this new effort will result in a more structured, high quality result. Again, the user wiki effort is/was fantastic and we are very thankful to Radioking that he took it up. Time for user wiki 2.0!