Libgdx Documentation Initiative

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!

11 thoughts on “Libgdx Documentation Initiative

  1. I have just signed up for users-wiki, was going to write an article about setting libgdx up with IntelliJ, as all guides on the net have small mistakes or are outdated. Going to wait till after the exams, though.

    A question: I have always felt that it was a bit pain having two sites to check for examples and usage. Could the best parts from the user-wiki be copied over and be added/merged to/with this wiki? Don’t know how libgdx-users material is licensed, though. I feel it’s better to have one GREAT doc than two OKEY that overlaps.

    And also a request for someone writing stuff: Most of libgdx is well documented and many classes have examples in the wikis of how to use them. However, I often feel that “this class looks great”, but I don’t know _how_ it should be used. I get it to work as I like, but maybe not in the most efficient way and I don’t think I always get as much out of a class compared to what it really can do. So instead of just explaining basic usage, please consider showing how this class or function can be or is used in a proper way with other classes.

    I would also like some kind of higher documentation(/articles) on what actually exists in the framework, and how to use it combined and best practices. E.g., when making a basic menuscreen in your game, there are maany ways to do it, all with their pros and cons. Those are not always easy to see by reading each doc by itself, and an article or similar would be great.

    I think this is a great initiative, and I hope this will succeed and make libgdx even better.
    Mats

  2. Yes, migration from libgdx-users wiki to the official wiki would be a good thing. I currently lack the time to do that. Hopefully one of the guys who’s already on the contributors list can do that?

    Best practices depend largely on your scenario. It’s pretty hard to enumerate all potential use cases and provide best practices. However, we’ll try to point out common best practices for classes like SpriteBatch and the like.

    The dev guide should cover pretty much all classes in the framework (see TOC of dev guide). Most of the articles are named in a way that it should be obvious what to use for a specific case. One high-level article giving a short list of usage scenarios plus involved classes is a good idea i think.

  3. Thanks for your reply. I agree with what you wrote, and it seems you grasped the essence of my messy post pretty well. :)

    Mats

  4. Why not just develop on GitHub to begin with? Would probably make the back and fourth manual crap easier. Other than that I love your work and I will try to contribute where I can.

  5. I understand the “if it isn’t broken don’t fix it” mantra but, you are still using it concurrently…seems like a nightmare to me. Meh semantics, both accomplish the same task

  6. Hi Mario,

    Although I did not look into the forum for many month and although I did not code anything libgdx related since 10/2011, I still feel connected to libgdx project.
    This is why I kept maintaining libgdx-users wiki w.r.t. to adding ppl as contributors.

    I just stumbled upon this blog entry from May 2012 and I appreciate your decision to open libgdx project documentation for all!
    This addresses exactly one of the main reasons why yatayata and I started libgdx-users project and thus makes it obsolete in near future.
    I will put a note on the libgdx-users project main page to announce this blog entry.

    Keep it up! ;)

Leave a Reply

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>