Amen and Amen again, sister.

Story: Linux Bug #1: Bad DocumentationTotal Replies: 0
Author Content
dinotrac

Nov 17, 2009
11:27 PM EST
I recently had the pleasure of dealing with nitty-gritty issues in the Joomla! CMS, which just about made me pull my hair out.

Joomla!, overall, is a nice CMS, but... like Ruby on Rails (another source of lost hair, though not quite as bad), full of conventions that just have to work, especially when you get into their interpretation of MVC.

Hint:

Simply providing an example and saying "This works" is not documentation. It's nice. It's a help, but...I probably need to do something different, and am likely to change something very early on. A little explanation of what things must follow what convention will save a lot of grief.

Oh yeah -- autogenerated listings of class structures are nice, but explanation and descriptions would be nicer.

Oh -- and for Pete's sake -- bringing the documentation together in an organized way is not a crime against humanity. Google and kin are great, but... the same key word can apply to user interactions, administrative entries, and --- gosh! --- development of new or extended functionality. Guess what's going to come up first, ad nauseum on the results lists? Hint: Probably not the stuff you're really looking for.

At least it's better than the libxml2 documentation, and we won't even go into Zope -- or, at least, the Zope of 5 or 6 years ago.

There's a lot of great FOSS stuff out there, but nobody should have to be a mind reader or code God to deal with it.

Document, guys. It's what professionals do.

Posting in this forum is limited to members of the group: [ForumMods, SITEADMINS, MEMBERS.]

Becoming a member of LXer is easy and free. Join Us!