Habari needs better developer documentation.
Posted on Saturday the 4th of August, 2007 at 2:30 pm in Asides, SoftwareThe Habari Project just released version 0.2. I have been watching it for a while now, but even though it has some features that I really like, it still hasn’t reached a point that I would consider switching this website from WordPress (mostly because I would have to rewrite far too many need-to-have plugins).
However, recently I started thinking about re-writing some of my plugins for it–especially what will eventually become INAP 3.0, but when I try to find reasonable plugin documentation, it just doesn’t exist–not even simple tutorials. There is a wiki for the project, but it is very well hidden and nearly empty. Now I don’t mind reading through the code to figure out what functions do, but even I don’t have the time to read through an entire project just to get started.
So for now I sit back an wait for some docs that at least give me a brief overview of how things work under the hood. Moral of the story: quick and dirty documentation is better than no documentation, so don’t wait until the end to write your docs.
Better documentation is absolutely a requirement! Just as the code will continue to improve, so too will the documentation.
What sorts of developer documentation would you find most useful? “How to write a plugin” ought not take too long to author. One of the primary reasons we haven’t written such a thing yet is because the places in which we execute plugin hooks hasn’t been formalized. We don’t know where folks might want / need plugins to execute in all instances. If you have an opinion on such things, do please let us know!
Reply to skippyWell a brief “How to write a plugin” tutorial would be nice, but I’m looking mostly for a “quick” primer on how Habari works. Nothing too in-depth, but just enough that someone who doesn’t know how it works under-the-hood can figure out what is going on. Basic things like what files are called when etc or the order functions are called.
The Habari team is probably sick of (or soon going to be sick of) being compared to WordPress, but a developers primer to the major differences or similarities (in the code, not categories verses tags) would be nice.
But whatever it is, at this stage, it doesn’t need to be too in-depth, just a general overview. That combined with a copy of the code nicely located on http://phpxref.com/ would be perfect.
Reply to AaronThere is, in fact, a Creating a plugin page. This needs to be improved, and integrated into the manual(s) shipped with the product.
Perhaps poorly named, the Habari workflow provides a jumpstart for how Habari works under the hood. That, coupled with the incomplete Habari classes might be enough to answer immediate questions.
Thanks for the feedback! We’ll make sure we improve the quality of the documentation before our next release.
Reply to skippyAye, I read the Plugin guide, but it needs to be a tad bit more in-depth. For example, a few of the plugins I would transfer from WordPress require priorities. The plugin documentation just say these exist, so I had to go dig around the code to figure out that to set them you create a function that returns an array priorities with the methods name as the key.
I read the workflow and found it very helpful,
Thank you for responding, I’ll be watching habari a little closer now.
Reply to AaronI agree — Habari needs better developer documentation. We’re excited to respond to these requests because we’d rather produce docs that would be useful to actual developers than something that would go unused or be difficult to navigate. As with anything in Habari, your input is welcome and we usually act upon it.
I should point out though, that documented source is a requirement for code submission. So every function in Habari should already be documented. As reported by Ohloh, 31% of Habari’s code is code comments, which is a bit higher than the average of 26%. As a result, the Habari XRef that is available (and is updated regularly from the SVN repository) is fairly complete and current.
Reply to OwenThanks for the link to XRef. Inline documentation is very helpful when you really start digging in the core, but is only moderately useful when you are still trying to get a feel for what comes next.
Reply to AaronCould you anybody explain me the XRef stuff ??? In the Habari documentation is written “This documentation was generated by phpdocumentor”, so I don’t get it. But I pray for better documentation too. I spent whole day by implementing asides according very short tutorial, because things are sometimes done by very original ways and man can’t get it. Especially if there is not plenty of time. It’s truth that 31% of Habari�??s code is code comments, but there is a need of something like Habari Workflow stuff, but much more deep. I´m going crazy from reading of code whole day and finaly I don’t know anything. WordPress is extremly easy to understand without any documentation for me. But I can’t say the same in case of HabariProject.
Reply to grolmussI agree, yes, there is a lot of documentation, but it is the wrong kind because it is not directly usable.
Xref is just an easy way to cross-link the function calls which makes reading the code easier, but it seems that they have changed to a different program than what they had when the comment was originally posted, so it isn’t as useful as it could be.
Reply to Aaron