I know that there is a system in the works that will help us to assess the relative value of contrib modules. But, a comment I read got me thinking... The person said (perhaps tongue-in-cheek) that they wish there was a rule requiring contrib module README files be at least 10k long and written in plain human English. I was wondering if it would be a good idea to start creating "real world usage of modules" pages in the handbook. For example, if we could get people who use various modules to write a quality summary of how they use the module to accomplish their specific tasks. It would allow people considering a module to see how the module is actually used, which is sometimes unclear from the simple module description.
I'm posting here first to get feedback about whether this is a good idea or not, or if it would be acceptable to the community. Any thoughts? Any ideas? Is this a redundant task? Does the "site recipe" section do this well enough already?
And yes, I would be willing to contribute to this project. But I don't want to waste my time if this is a bad idea.
Comments
Sounds like a fine idea
but I don't get why people aren't already writing such reviews right here in the forums already. If people already havethe desire to create those type of things, why aren't they doing them already and getting them finished for potential inclusion in the handbook by using the forum as a space to do so? I just think it would be a lot easier to show the documentation team some finished reviews rather than wait for some sort of official approval first.
"And yes, I would be willing to contribute to this project. But I don't want to waste my time if this is a bad idea."
If you have the desire, then write the documentation and put it here in the forum.
I personally think this is a
I personally think this is a good idea, but it would be an even greater step forward in my opinion if the "README" files were automatically included in the Handbook per each module. If this were considered a worthy enough task, I personally would manually enter any README documentation from modules I am currently using. Heck, I'd even download ones I'm not using and upload the README. Why should the info be available in the download, but not in the Handbook?
Drupal's so easy, even I could do it.
http://www.kfol.org/
Real World Examples
It takes a different metal set to design a module than to explain it.
Thats why we have tech-writers and different people write instructions.
Often in the form of stept1, 2 etc.
The quality of readme files has improved over the last couple of years. Except when a module is updated often the readme never changes.
Maybe what need is a partnership between developer's and writers(documenters).
From the maintainers point it would save time from answering all the questions that could have been explained in the readme files.
Count me is to help. Maybe a template would help. step 1, step 2 etc. Even the expiation that this module has no settings options would be helpful.
Ron Mahon
The-villages-info-center.com
Yet another Drupal Site
Maybe what need is a
I often think about this when I hear coders say that documentation isn't their forte'. I think a partnership is a great idea. I think it should even go so far as being a requirement. If you want to contribute code to Drupal, then you are the "module maintainer" but you should also be required to find one other volunteer to be your "documentation maintainer". Or at the very least, there should be some kind of relationship established. An acknowledgement that a certain module has or has no documentation maintainer. I would gladly volunteer to be such a person for a few of the modules I use.
In my opinion, this has many advantages. You have someone who has a direct relationship with the module maintainer, who can be notified of changes in the module, how it might affect UI and function, and will get a bettter sense of where the module maintainer is going with the module and hence be able to write better documentation for it. Right now, the random documentation strategy has many gaps and is causing many otherwise brilliant modules to be relatively useless to the general public.
Drupal's so easy, even I could do it.
http://www.kfol.org/
This is a brilliant idea. I
This is a brilliant idea. I know I could probably help maintain documentation on at least one or two modules. With a broad community effort, this work could be spread over a lot of people. Do you mind if I post a new thread with this idea? I could start to solicit module developers who feel that they need some help with documentation. Imagine if each module had a robust user manual right here on drupal.org!
some do
Views and CCK modules do have a lot of documentation. Some others have additional documentation as well. There is nothing preventing people from adopting a module or group of modules to focus on.
We have asked for people to volunteer to do this before with occasional results. As to making it a requirement to contribute a module? We're not quite there yet.
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide
I don't mind one bit.
I don't mind one bit. Please post a link to that thread here. I suppose I already have an unofficial documentation relationship being discussed with the maintainer of the Liquid module. Don't forget to mention having the document maintainer's name on the module page as well as the module maintainer's.
Thanks
Jonathan
Drupal's so easy, even I could do it.
http://www.kfol.org/
Sorry, I couldn't wait. I
Sorry, I couldn't wait. I started the thread myself at: http://drupal.org/node/142483
Thanks,
Jonathan
Drupal's so easy, even I could do it.
http://www.kfol.org/
=-=
sounds like you are describing this area of the handbook see: http://drupal.org/handbook/config/contribmodules
which anyone can add pages to.
On a related note...
On a related note, I recently started doing more introductory screencasts for Drupal, rather then demonstrating "taxonomy" or "nodes" or specific features/components of Drupal, the lessons cover things such as, setting up a single user blog site for example.
http://drupal.org/node/139205
I totally agree that the real world examples are a great documentation tool, I'm willing to contribute short videos for other areas as well.
Here 's something from
Here 's something from AdSense Injector's Handbook Page - http://drupal.org/node/121883
This may already be documented somewhere, but it was not clear at a glance. The frontpage of this handbook page has a nice format which makes me think how important standard formatting can be. If there is already a page that defines this standard, someone please provide a link. If there is no page, I will submit an issue to the documentation team regarding establishing a standard.
This module basically has 4 FP sections.
1) Intro - What is it?
2) Rationale - Why would you want to use it?
3) Usage (Would be better titled as Prerequisites) - What are this module's dependancies?
4) Coming Soon - Module sections planned to be written.
In addition to those four, here are some sections I think would be useful for EVERY module. (Child pages rather than front page.)
1) Installation.
2) Table Structure.
3) Sub-modules that are installed with the main module.
4) ALL Administration pages with explanations.
Not to mention plain old general usage of a module, which is more of what this particular thread is about. In light of what I have just listed, it feels like each module should have a "recipes" section (depending on the nature of the module). Enough blabbing from me. What does anyone else think?
Drupal's so easy, even I could do it.
http://www.kfol.org/
Ooooooooo
The audio module page even has a FAQ!
http://drupal.org/node/87691
Drupal's so easy, even I could do it.
http://www.kfol.org/