1
council
Better Module Documentation
  • 2005/1/5 13:39

  • council

  • Not too shy to talk

  • Posts: 184

  • Since: 2004/12/18


This is a plea for better module documentation. And I realize some of you developers are not native English speakers but this plea must be made anyway.

The documentation for most of the modules is terrible and getting worse. There are modules which contain no description of the module save the name. There are modules in French, Russian, and Swahilii.

Why someone would put all the time and labor in a module and not include a sentence about what it does, is a mystery.

Why someone would not include documentation in the universal internet language -- ENGLISH! -- is a deeper mystery.

And the irony is, a few of these modules actually do what they're supposed to do -- so why do you limit their use by not including basic descriptions?

Mark my words, the day will come where some of you guys won't even name your modules. You'll give them numbers like "007" and "911" expecting the end user to figure out that one is sypware while the other a security patch.

Stop this madness! Write the documentation!

Anonymous

2
hervet
Re: Better Module Documentation
  • 2005/1/5 13:53

  • hervet

  • Friend of XOOPS

  • Posts: 2267

  • Since: 2003/11/4


Council,

I think that if there were only english people to write modules and Content Management Systems, they will not exist and there will be less modules.

That's my first point.

Secondly, you wrote :
Quote:

There are modules which contain no description of the module save the name. There are modules in French, Russian, and Swahilii.


and later :
Quote:

Why someone would not include documentation in the universal internet language -- ENGLISH! -- is a deeper mystery.

Do you realise what you are saying ?

How skill are you in other languages ?
Will you be capable to write and/or talk in french or russian or any other language than yours ?
Excuse the rest of the world to have a so poor english.

It's easy to criticize, it's better to be productive and positive.
You should, if you are so good, join a team and correct our so poor english.

PS : Et bonne année.

Hervé

3
Herko
Re: Better Module Documentation
  • 2005/1/5 13:59

  • Herko

  • XOOPS is my life!

  • Posts: 4238

  • Since: 2002/2/4 1


heh, I think almost everyone on the face of this planet knows what the numbers '007' and '911' mean... Bad examples

Herko

4
jegelstaff
Re: Better Module Documentation

LOL! This is a funny thread.

I would agree, however, that documentation is lacking for many (most?) modules.

I would also say, though, that writing good documentation is just as hard as writing the modules, and few people have both sets of skills.

In the end, bad docs are probably better than no docs. And docs can't help but give your module a wider audience, which should be a motivation for some module devs.

As for the language, hey, write it in whatever you can, there are rudimentary translation engines on the 'net, and my unscientific opinion is that most people, at least outside the US, speak at least a bit of another language besides English.

For instance, here in Canada it's actually the law that we speak in English and then in French when talking in public. (Unless you're in Quebec, where bill 101 mandates that you have to talk in French first, and then you must use a quieter voice when talking in English.)



Thanks for reading, a bientot,

--Julian

5
carnuke
Re: Better Module Documentation
  • 2005/1/5 15:27

  • carnuke

  • Home away from home

  • Posts: 1955

  • Since: 2003/11/5


Julian,

In essence what you say is justified, the challenge is how do we persuade developers to do it?

We cannot retrospectively document all modules, although we have done this for some of the official modules.

I think the new QA standardisation will take this subject into account and I hope it will produce a format for documentation for all future releases.

The documentation team (ha) is ready to participate in that process, BUT we do need more volunteers to make this possible.

6
irmtfan
Re: Better Module Documentation
  • 2005/1/5 15:42

  • irmtfan

  • Module Developer

  • Posts: 3419

  • Since: 2003/12/7


i totally agree with Julian and carnuke.
we must have any documentation for modules.developers can write a guid for modules but IMHO they dont have enough time to write perfect documents and QA team can help them in this case.
but QA team must had a PLAN for documentation of modules and maybe can use documantation format in doc.xoops.org or create a documentation team inside?

7
Dave_L
Re: Better Module Documentation
  • 2005/1/5 15:54

  • Dave_L

  • XOOPS is my life!

  • Posts: 2277

  • Since: 2003/11/7


I plan on pushing for user documentation to be one of the mandatory requirements for a module to become fully certified. That would apply to existing modules as well as new modules, when we start posting the module certifications. Maybe that will help encourage developers to document their modules.

8
Mithrandir
Re: Better Module Documentation

Basically I agree, however I also recognize the need for a "skeleton documentation template" with headlines and a short description of what kind of information goes in each section.

Something like:
Quote:

Introduction
Describe what your module is about, who should use it and for what

Get Started
Installation/Update/uninstallation - how is it done?

How does one start using the module? Are there categories to create first? Should the user start in the module administration setting up the basics or is it a matter of diving into the frontend and start dishing out content?

Administration
What are the options in the administration menu, go through each page and describe its purpose.
What does each preference in the module preferences do (if applicable)?

Frontend
Which options are available to the regular users/anonymous users? How do they use the module and for what?


I think I have done reasonably well with my User's manual for obs_classroom but a standardized format with just a few example modules would be great. I know you have done so with some of the modules distributed with the core packages, but highlight it more so more people are aware of it - and cut it down to a basic instruction in how to write documentation. Will help a lot, I think.

9
Herko
Re: Better Module Documentation
  • 2005/1/5 16:04

  • Herko

  • XOOPS is my life!

  • Posts: 4238

  • Since: 2002/2/4 1


Nice skeleton Mith I'd like to see the following chapters added:
Install/upgrade/uninstall instructions (can also be put in the INSTALL.txt file)
Support (where cam the user get support for this module)
Report bugs/submit hacks (where can the user submit bugs and hacks for this module)
Translations (where can the user find more langauges for this module)
Credits (last but not least, the who did the work for this module, and what is it based on).

Herko

10
carnuke
Re: Better Module Documentation
  • 2005/1/5 16:12

  • carnuke

  • Home away from home

  • Posts: 1955

  • Since: 2003/11/5


Yes, work has already started on defining documentation standards and processes. see previous previews here:

http://houseofstrauss.co.uk/files/docs.htm (standards)
http://houseofstrauss.co.uk/files/cmap/1.html (processes)

These were done several months ago and probably require refining.

Login

Who's Online

189 user(s) are online (120 user(s) are browsing Support Forums)


Members: 0


Guests: 189


more...

Donat-O-Meter

Stats
Goal: $100.00
Due Date: May 31
Gross Amount: $0.00
Net Balance: $0.00
Left to go: $100.00
Make donations with PayPal!

Latest GitHub Commits