As per @jhodgdon's request, this is a followup to comments #18 and #21 from "Make a curated docs section" at http://drupal.org/node/1291058.
The guidelines at http://drupal.org/node/161085 are, indeed, very good (if only all developers would follow them!) - I don't see numbered steps suggested anywhere, though, and I think it's worth discussion.
As simple as it sounds, having numbered steps is not only somewhat soothing when it comes to executing a task, it's also helpful for bug reporting and support requests by being able to say something like, "The process fails at Step 5."
I also do think that having a working demonstration of the module in question (or at least screenshots) should be practically mandatory where applicable - and hosted on Drupal.org, if possible. I've seen many "dead" pages where demonstration pages are no longer maintained, meaning that the only way to find out if the module provides the desired functionality is to go through the install process yourself.
This is tedious, time-consuming, usually a waste of time and can easily lead to bigger problems when conflicts arise. I don't believe it's too much to ask for developers to deploy a simple demo site - it would be much appreciated by the community!
OK - that's all I have to say - thanks for taking the time and for the great work you're doing here!
Comments
Comment #1
jhodgdonOK. So the ideas I'm seeing here:
a) Number the doc suggestions for module contributors on http://drupal.org/node/161085
b) Suggest screenshots and/or demo sites be required for all modules. Note on screen shots - there's an effort going on (I saw a page on groups.drupal.org a month or so ago) to have volunteers take screen shots and submit them to the module developers... you might look for that...
My thoughts: Having demo pages on drupal.org itself is not going to be possible - because drupal.org would need to run all the contributed modules, and it just can't. And requiring all module developers to maintain their own demo site is not realistic, in my opinion. But screen shots are a good idea... others may have different opinions!
Comment #2
bcobin commentedUh... duh. Sorry about that - I wasn't thinking. Of course, you're right.
Some developers have been nice enough to set up demo sites on subdomains, but that is too much to ask. However, a case could be made for certain modules, particularly where setup can be confusing and there's a lot of interest. A demo site could save the developer time analyzing and responding to bug reports, for one thing, so the extra effort at the beginning could well be worthwhile in the long term.
If the bug is reproducible on the demo site, that's a big help, and if it's not, then the problem lies elsewhere. Simple.
I do think it's something worth considering as a note in the guidelines for module submission - again, only in certain cases.
Comment #3
jhodgdonComment #4
jhodgdonRegarding demo sites, we now have simplytest.me, which allows anyone to test out any module available on drupal.org pretty easily.
So... it looks like the other recommendation is to number the suggestions on https://www.drupal.org/node/161085
I think that the DL list format at the top is actually more readable than a numbered list (because it has headings), but I think numbering the UL list at the bottom is a reasonable request. So I took care of that.