By knalstaaf on

As a unexperienced Drupal user it's really frustrating to look for a particular module, and up on a page which describes the module in some extraterrestrial jargon.

Table Wizard for instance. The name of the module suggests it's a way to display tables with results or data. But the description succeeds in taking away your confidence in it:

  • It allows surfacing any table in the Drupal default database through Views 2.
  • Relationships between the tables it manages can be defined, so views combining data in the tables can be constructed.
  • It performs analysis of the tables it manages, reporting on empty fields, data ranges, ranges of string lengths, etc.
  • It provides an API for other modules to views-enable their tables.
  • It provides an API for importing data into tables in the Drupal default database (automatically doing the views integration above).
  • It is bundled with an implementation of this API, for importing comma- and tab-delimited files.

Phoow! ... is this really what I'm looking for - I don't know. Does it provide screenshots? No, use your imagination.

Sure it's relevant information, but please, show a graphic example of what you're talking about (or give a description that's easier to comprehend). Because I have no idea what that module eventually does.

Edit: I took the effort of installing the table and the modules that are required for it. It's definitly not what I'm looking for. This is so Drupal, isn't it.

⋅ Categories: Drupal 6.x

Comments

dman’s picture

dman commented

As an inexperienced internet user, you may find you'll get better results if you post this documentation request in the issue queue of the module you have questions about. The developer there may be able to provide you with a screenshot of what - if anything - a database table looks like - to supplement the other pages of documentation already written up in the handbook (and linked to from the project page).
From the description, I'm not sure what a picture of a database lookup utility will look like...

The developer will probably not see your posting in general discussion - especially if you aren't able to provide links to the problem.

.dan. is the New Zealand Drupal Developer working on Government Web Standards

knalstaaf’s picture

knalstaaf commented

I'm directing this advice to all module developers, Table Wizard is just an example. Contacting the author or posting in the modules issue queues for a simple screenshot or a little more explanation is a huge waste of time, as well for the user as for the developer.

A simple screenshot (which takes about a minute to create) or a more comprehendible description could save us from a lot of trouble.

This is how it should be. Compared to Wordpress.org, Drupal.org looks blatantly primitive.

You could say "no one is forcing you to use Drupal" once again, but when you someone hands you a Drupal site in order to adjust it, you can just tell the guy "sorry, dude, but I'll have to rebuild your whole website with another CMS."

dman’s picture

dman commented

It's all about contributions.

Seeing as you have now taken the time to install and evaluate the module - which I agree can take a while - you are now in a position to spend that extra minute and take that screenshot you want and post it up as documentation for the next seeker!
The contrib modules run off the drive provided by the contributors, and contributing improvements to the docs is just as valid as contributing patches or code.

I don't see how you can say that asking specifically for something you want is a huge waste of time when for the developers, adding something they didn't think was necessary may be a waste of their time.
Look, I agree that many project pages could do with more illustration or explanation. But I don't know what a screenshot of a database API would look like. You have now seen the screen personally, so you can copy up the screenshot you wanted. That would be helpful!

I've seen outsiders insisting that the volunteer developers should all provide working demos also. I personally wrote up the guidelines for module documentation (including a mention of screenshots). But they can only be suggestions. And can be followed with help from people who think it's important enough.
I contribute additional documentation all the time.
I started off puzzled or needing to evaluate something, tried out a module, took notes, worked out how it worked, or what was missing from the docs (or asked questions), and sent my adjusted notes back into the issue queue. That may help the next person.
And so things get better.
I find that more constructive than just complaining at the community at large.

.dan. is the New Zealand Drupal Developer working on Government Web Standards