Jump to content
Sign in to follow this  
  • entries
    45
  • comments
    115
  • views
    54986

Documentation woes

Sign in to follow this  
Kylotan

417 views

I use a lot of free and open source libraries, and the main problem I find with them is documentation. Strangely, it's rarely that there's a lack of documentation, but more commonly that the documentation provided is inadequate.

The typical incarnation of this is where someone has processed their entire source code with Doxygen or something like that, in the almost completely misfounded belief that an unordered list of function names and objects is enough information to get started. It is much like giving someone 100 identical keys when they ask how to unlock a certain door. Why make them dig through the whole lot? Anyone with a decent IDE (or a reasonable command of their toolchain) can look up function names and parameters in seconds anyway. Providing an HTML interface to it all seems largely pointless unless you're going to add value with diagrams and so on.

Today I came across something less common - the opposite extreme, where the authors have gone to lengths to ensure that you have an easy and well-worded tutorial, yet have seemingly forgotten to provide any sort of useful reference that doesn't involve reading a long block of prose. My culprit for today is the Lua documentation. The reference manual is okay, but feels disorganised. To find something within, you have to look at the table of contents, pick a likely-looking topic, and hope for the best. I wanted to put one table inside another using the C API, and had to chase around several sections before discovering that what I needed was elsewhere on the web. Lua also has a lot of very helpful functions in the auxiliary library, which aren't documented properly anyway. This is somewhat ridiculous as they make life so much easier, but I digress. There is not even an index where you can look up function names to see exactly what they do. So whereas other documentation drowns you in detail and leaves out the big picture, the Lua docs give you their big picture but don't tell you the details of how to draw your own picture.

So, what do I think documentation needs? It's quite simple:

1) Tutorial/Overview. I want to be told what the software does, and ideally be given some short sample code illustrating exactly how it does it. Talk me through it line by line, so I get a feel for the interface, and can see how I might modify it to suit my needs.

2) Hierarchical description. Give me a table of contents where the functions and classes are described, arranged according to sensible groupings of functionality. This allows me to translate a task in my head to a relevant section of the documentation. No function or class should be omitted, least of all convenience functions. No function should be described without an example. Even if that example is just an uncompilable snippet, it's still better to see it in context. All functions and classes in a section should be summarised together at the start of that section with a one-line description for each. You should be able to drill down from the top level (seeing which module you want) to the sub-section (seeing which function you want) to the individual function (seeing which parameters you need). Feel free to generate this automatically from the code providing there is a clear and obvious hierarchy. Most automatic doc-generators do not do this at all. (Or perhaps I should say that nobody is using them in such a way.)

3) Index. After a while I will vaguely know about the existence of functions or objects but will not know precisely what they do. I may have a rough idea that they might be useful to me, or I might just be interested in finding out for future reference. But if I don't know what they do, I cannot look them up in the table of contents. So an alphabetical index is vital. Don't make me wade through your tutorial again to find the one place where you used that function.
Sign in to follow this  


7 Comments


Recommended Comments

The version 5.1 documentation has improved on this a bit. They have not linked it in the documentation section of the homepage yet (its included with the beta sources) but it does contain a nice function index with at least a line or two documenting what each does. This is the first version of the docs where it seems the entire lauxlib is entirely documented. It's helped me alot with my current Lua work.

As for tutorial/examples of code I have found Roberto's PiL to be a great sink for that kind-of information.

The second edition is supposed to be out this March which will contain some of the new stuff to 5.1 (module/packages, function environments) that have been causing a bit of confusion.

Share this comment


Link to comment
Issues like this is why I prefer books over anything else, they tend to come with an index for fast lookup and often examples in the flow of texture which is always handy.

Plus, dead trees are easy to read away from the monitor [grin]

Share this comment


Link to comment
I can't agree with you more. A big issue with me is tutorials. The author(s) should provide at least three official tutorials/examples used to get new users started.

Share this comment


Link to comment
I think what you're asking is that people actually write a real manual that resembles the structure of a book. I can't agree more.

It's a point bearing in mind for people like me who write libraries.

Share this comment


Link to comment
Zorbfish, my problem with PiL is that finding anything specific in there is difficult. It's fine if you have the time to read it from start to finish and memorise bits as you go along, but as a reference it's little help. The reference manual is also surprisingly poor in this regard; although things are roughly organised, it's still done so in quite an informal way and it is hard to determine exactly what you need for a given task. Lua has plenty of walkthroughs and tutorials but as soon as you need to step off that track it gets a lot harder. This is possibly why so many binding libraries for it exist despite Lua only really requiring 3 or 4 lines of binding code for each function. It just happens to be difficult to find out exactly what to put on those 3 or 4 lines.

Share this comment


Link to comment
I don't have much to add by way of suggestion - but I most definitely agree with what you're saying.

API's/libraries/etc.. are just that bit easier (perhaps even enjoyable?) to use when you aren't spent spinning round in circles trying to figure out WTF the documentation means.

Jack

Share this comment


Link to comment
I completely agree. I think doxygen is great, but it's simply too overwhelming when you just want a simple answer to the question of "how do I do X?" On the project I'm working on (HoA), we have several levels of documentation.. There's doxygen at the lowest level, then there's comprehensive documentation for each major engine component, then finally there's a "quick start guide" which is basically a set of short tutorials, which really helps for people who are brand new.

Share this comment


Link to comment

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!