Can code be the documentation in open source developer tools? How frequently is it?

Question

It's understandable that after a big development effort, some OSS authors deem reasonable that the project users should make an effort too in order to get started.

Can the source code effectively be the project's documentation? Does it need to be structured in a particular way in order to achieve this? And how often is this approach taken?

Of course this only would be feasible if the project is aimed to developers, and written in the same targeted language of the application (e.g. you can't understand the V8 engine only knowing JavaScript).

Answer 1

NHibernate is OSS. You can download the source code for free, make your own changes, recompile it, push that source code back to the VCS, etc etc. Does Ayende require you to dig through the code, and that of Castle's DynamicProxy, in order to effectively use his library to implement your persistence layer? Of course not. The NHibernate community provides a pretty good set of documentation and best practices for using the NHibernate library. Similarly, the Fluent NH add-on has decent documentation; you don't have to dig through the library's code to figure out what it does and how to use it.

In short, even OSS should conform to the "black box principle" from the perspective of the end user.

Coders expect their libraries to be packaged much like their electronic equipment: they expect to receive an instruction manual along with this "black box", that tells them how to hook it up and how to communicate with it. If they don't receive a manual, the smarter among them will look at what does come in the package, will expect to see very clear labels for where things plug in to it, and will assume no specialized knowledge is required for operation once it is set up properly. If neither of these is true, the coder will likely be calling the library's developers for help, much like you'd be calling tech support if you didn't have all the info you needed to set up your TiVo. The last thing you would do is crack the seal on a brand-new, warrantied piece of equipment and try to trace through it yourself, much like the last thing the coder would do is pull up and trace through the library's source code for a clue as to its inner workings.

Similarly, OSS projects that aren't effectively documented in some other way than code fall into one of three categories:

• infant projects - the documentation is simply not yet well-developed because the focus is on proof-of-concept and thus working code. Users of the code at this stage are "beta" testers, and understand its "as-is" nature on all fronts including documentation.
• extremely simple - the stated purpose of the library, the names and signatures of the classes and class members as viewed from some object browser or by JavaDocing the JAR, plus maybe a simple demo, tell the user all they need to know.
• dead or dying - nobody wants to take the time to figure out how to use the library by trial and error, or by inspection, so nobody's using it.

Answer 2

Source code is not a documentation.

I have seen too many (excellent) projects with no documentation, only source code and some tutorials. My latest example is Lutece (a French CMS : I spent a lot of time to understand how to use it, and what I can do with it. It was horrible).

Ideally, documentation would be written when you are developing your application. Unfortunately, a lot of people don't write any documentation (not Javadoc for Java projects, ...), and think contributors will write tutorials, wikis, documentations. If there is no initial documentation, nobody will try to help you, nor discover your work.

If you can make a good documentation, and if you have enough time, please, make it ;)

Answer 3

No, I don't think code should be documentation. And I don't think it matters that much whether or not it's an open-source project.

A lack of documentation (other than the code itself) will be a turn-off to many potential users and contributors. I've ditched or avoided using some libraries for other open-source libraries simply because the very scant tutorials were far too simplistic (real business uses were more complex and needed featuers that were never clearly explained or documented) and the API documentation amounted to little more than function: SetParamX() - This sets param X. Code alone also does not easily capture higher-level business requirements or specifications, such as param X must be a valid subnet mask, unless param Y is set to "foo". To infer this requirement, you might have to read through 100 lines of code and jump through 3 or 4 layers of method calls to find out exactly what this requirement is.

How eager would you be to work on a project that you have decipher yourself from only the code? I know I wouldn't, whether it's an open source project, or some internal corporate project. At least with internal projects (at least here), this is rarely but not never) a problem - and if it did happen with an internal project, I could probably find the person who wrote the code and ask them questions.

Answer 4

The word documentation means many things - and for most open source projects that's a problem.

While leaving aside many details, i would primarily classify it in three parts -

1. End user documentation - where people are likely to only use the end product. By far the most common and minimum you find in OSS projects is 'man page'.

2. API documentation - here you assume that people are looking at the internals of your modules but only as a black box - mostly by linking the libraries. (e.g. use a video codec library to build your own media player). One of the excellent examples is GNOME, GTK documentation for application developers.

3. Developer documentation - here is where you assume that people are actually going to contribute towards the core internal logic to enhance it or scale it.

The need and method to create all three types of documentation is different.

• The end-user level documentation certainly cannot be done inside the code. Typically these are external documents like user manual; they cannot be inside the code (even if they are carried inside the tar.gz of the source codes).

• The API documentation can often be done (and usually best done) using doxygen kind of framework - where comments above the functions can be translated into fully formatted pages. This way, efforts of formatting is saved and consistency is achieved - while documentation's core details are still handwritten. Also, we can see that when API evolves or become un-compatible, modifying comments can help make new version documentation easier. Another such thing i have seen is to write a small - "api_example.c" file that explains how to use it. For most medium size projects this is enough.

• Last but most important is the design documentation that explains the inner workings of the code. Hard to say but this is rare even in professionally paid companies. Many a companies prefer to make "design documents" somewhere outside the code but unfortunately as code evolves these remains disconnected from the docs. In such scenario, having lot of comments - and comments on top of comments actually help much better. It is usually NOT complete - but most often, if the developer is intelligent enough, what really matters is to comments all the non-obvious parts in plenty. This approach always works much better.

In fact keeping this in mind - one should care fully draft higher level documents only to explain terminology and broader business logic and leave the details explained inside the code (and let it evolve along with code). External documents almost always never evolve as fast as code - so they should be limited on dependencies and details.

Dipan.

Answer 5

If you want the OSS project to be a success you really should provide ample documentation for the users. Most OSS projects have a relatively small user base that cares to delve into the code.

If I am not directly contributing to the project in some way then the only time I look at the source code is when I feel that I have discovered a bug and wish to either fix it myself or notify the project of the bug I had found and where in the code I feel the problem is.

I can't say how many times I have evaluated a complex OSS project to find no substaintial documentation whatsoever. Many times if I have another more transparent choice I will go in that direction partly because I don't wish to spend days of trial and error figuring out how to use it, or because I feel the project is too "green" or too "amateurish" to commit to.

Answer 6

Nearly all the popular Java OSS packages I've used have been well documented with javadocs. To be technical this means that the source code contains, not is, the documentation.

Whatever the case, these are generally some of the best documented systems I've used. I believe this is due to keeping the documents with the source code, allowing them to be updated in parallel--then splitting out the docs later.