How do I learn a poorly documented open source framework?

Question

What's your way to learn an open source project if the project is poorly documented?

Read source code?

Answer 1

Read the source, Luke.

Seriously, I see no other way. Plus: for me, the learning is the fun part...

Answer 2

Sometimes, documentation for opensource frameworks is not free. You need to buy it. Maybe, it is your case?

Answer 3

If there is a forum or a community available, then you should ask there first.

Answer 4

If there is little or no documentation / examples, then yes, reading the source code is about your only way forward.

If you are new to the language or concepts behind the framework (e.g. the MVC pattern), I would recommend you try and find something with better documentation, as you will be faced with not only trying to understand the what the code is doing but also why it is doing it.

If you are familiar with the language then it's certainly worth working at it. If you are able to get the framework working, then at the very least blog about it so others in your position can get some help. You could also consider contributing to the project by writing the documentation....

Answer 5

Find a different framework that pays attention to its users more.

Answer 6

If the documentation is poor or non-existent, I refuse to learn the framework. There is no point in working with something that might or might not work as I think it does. Basing my own work on something like that means building on sand.

Answer 7

I'm faced with this for a control I'm using on the Insight project.

Here's what I do.

1. Read the source code, if it's available.

2. If the source code isn't available, use Reflector to get the source code, and read that.

3. Familiarize yourself with the community, if one exists. If there's a forum group, join it. Post your questions, share whatever your knowledge is, and become an active participant. Other users are more likely to help you if you help them.

That's all I've got. If none of those work for you, I strongly suggest seeking an alternative if that option is available to you.

Answer 8

I hate to say it, but this is often the case --even in a business environment. If you really like a particular project, you're just going to have to start digging in and learning it. One way I have gotten started with undocumented libraries is by first creating a class diagram in Visual Studio. If the developers have been careful about their naming conventions, the classes often document themselves and you'll be able to see their interactions. Otherwise, it really comes down to playing around with it.

Rather than jump in and try to tackle the source head on, all at once, I would recommend you have something that you can work towards. For example, look through the bug/feature list. Start with something simple and then work your way up. In time, you will become more and more familiar with the code base.

I certainly don't encourage people to avoid writing documentation, but I would suggest all developers become comfortable working with code that hasn't been documented.

Answer 9

I asked something similar some time ago.

Answer 10

As was mentioned in the link posted by Chrys, you can try using a source code documentation tool to generate documentation. You can run Doxygen or something similar over the source code of the framework, and set it to not exclude any undocumented functions or classes etc. If you really like, get it to inline function source codes, generate inheritance, include, collaboration, caller, callee and template instantiation diagrams, and you end up with a fairly comprehensive overview of the internals of the entire system.

Also, some poorly documented projects have strong communities behind them trying to get something together, but haven't finished getting something good out. You can join their mailing lists and ask questions as you go along.

Otherwise, be prepared to do a lot of trial-and-error.

Answer 11

Study it, document it and send patches back to the project so the next poor soul doesn't have to struggle.

In the mean time, ask yourself why you are struggling so much with an undocumented framework? If its that undocumented, clearly, the benefits of using it are either over hyped or not well described.

Answer 12

There are folks who like to write unit tests to dive into new code.