Mod and add-on documentation request

[Wolfmont]

I'm just throwing this out there for addon developers to think about, if they will.

In the last few days I've installed some add-ons to help with my store. One of them I managed to get up and running by pestering the developer with questions and by being sort of lucky.

One of the things I did in the past was to work as a documentation specialist and curriculum developer for technical stuff--specifically software. I have a lot of respect for software developers and the work they do. They have skill sets and knowledge sets that I simply don't possess, and for the most part they do their job very well.

Problem is, most of us (read that as the end-users of the products) don't have that same skill set and knowledge set. My experience with software developers has been that they focus on getting the program to do what it needs to do, and then walk away. That's fine when a software program has an easy-to-use and intuitive interface. But when that software (as most of these mods do) requires poking around in the guts of the associated database, or modifying lines in files by doing some hand coding, it just doesn't work!

As I stated in another post, the directions, "Turn right at the red light and go 1/2 mile, then left and you're there," seem to be very clear and concise. But not all of us know where that red light is located... or even if we are approaching it from north, south, east or west.

If you have written a mod and it requires that I go into a file and modify a line of code in some way, is it too much to ask you to specify exactly what file that is, and the path to get to it? Lately I've tried to use a couple of mods and although I am sure they work beautifully, how to make them work is beyond me. The documentation is fragmentary and incomplete at best.

Please, if you are writing a mod or add-on, write some documentation that not only tells me exactly what the new line in the file needs to be, but exactly what file it should go in and where that file is located. We don't all have your level of knowledge, and although it may be intuitively obvious to you, it probably isn't to many of us.

Thanks!

[kobra]

Documentation has been as issue for sometime.
I was part of a group that offered to write documentation for the cart but for what I saw as incosequential reasons, this was not embraced by the DEV team.

I hear your pain but expect that it will fall on deaf ears

[Wolfmont]

Kobra,

That's really sad, because good documentation turns what is a fairly good program into an outstanding program, one that rises head-and-shoulders above its contemporaries.

It's also sad because it indicates a total lack of concern for the ultimate consumer of the product, the end user.

[Crunch]

The Rules for Contribution/Addon Submission has a section on "Documentation Requirements," but perhaps it's not actively enforced.

[Wolfmont]

Crunch,

Wow. Since I'm not a developer, I had no idea about that requirement. Obviously it's not being enforced, not even in a cursory way.

Here is what the requirements say:

1. Complete documentation for the contribution must be contained in the contribution's distribution zip file, preferably in a file named "README-addonnamehere.TXT". Using a URL shortcut/link to point to another website for readme and/or install/uninstall documentation is not acceptable.

2. The author should be acknowledged - and a single link to their site is acceptable as is a tasteful request for donations (a single statement about where to send donations is acceptable).
Prior authors/contributors should be acknowledged.

3. Documentation should include clear steps outlining what to do once the contribution has been unzipped, including where to put the unzipped files and how to do any database updates/changes.

4. Documentation should be written with the "newbie" in mind ... ie: Don't make assumptions that the person using the contribution has any more understanding than how to unzip the file. This helps address the lowest-common-denominator skill-set and helps minimize support questions which can cause frustration and time drain on the author to supply support.

5. Documentation should include uninstall instructions in case someone wants to cleanly remove the addon from their store ... without breaking normal operation or leaving old fragments/data behind. This should address any files to be removed, any folders to be removed, any permissions changes to be undone, and any SQL changes/deletions applicable to the addon.

Personally, I'd like to see these requirements enforced. If the mod or add-on doesn't meet the requirements for documentation (including the idea that it should be written for someone who has no idea how to do anything beyond unzipping the file), the mod should be dumped from the list of addons... OR the developer should create documentation that follows the requirements.

It's only smart, really. Is it easier to write a good set of instructions on what to do ONCE and post it along with the mod, or is it easier to have to answer email after email, or post after post, with questions about how the bloody thing is installed and set up?
I think the answer is clear.

Thanks for bringing those requirements to my attention, Crunch.

[Website Rob]

The question posed in the first post is somewhat of an interesting dilemma as, one one hand you could have an excellent module which a lot of people could use whilst on the other, it may not have clear and concise Instructions as per the Rules for Contribution. Does that mean the module should not be included in the downloads? Obviously not as many modules are in this situation and have been included for downloading.

A good case in point regarding documentation is the Zen Cart Manual created by Goh Koon Hoek. Here we have someone who took it upon himself to create an almost 400 page manual to better help people understand and use Zen Cart itself. Is the Zen Cart dev team at fault for not creating one themselves even though there is "some" documentation provided with the script? Should the release of Zen Cart have waited until it, itself, met the Rules for Contribution? Who is to say?


My personal pet peeve is where a coder has provided a module or even a complete script and, even though the coding may be good and work as advertised, the HTML formatting is absolute garbage. One could also argue that coding without good layout should also be cause to have the coder's knuckles smartly rapped. Which, by the way, is one of the reason why I chose to focus on using Zen Cart; it has good coding and good HTML layout.

My point is that it all comes down to contributing. If someone is willing to take the time and put together a well thought out and executed module, perhaps they can be forgiven for not covering "all" that is technically required. Some modules do not even meet the "well thought out and executed" part and those are the ones I have to wonder about being included.

[DrByte]

The Rules for Contribution/Addon Submission has a section on "Documentation Requirements," but perhaps it's not actively enforced.

The rules about documentation requirements were recently updated. Contributions submitted prior to the updates may or may not be in compliance. With thousands of addons already submitted, it's impossible to go back and force authors to submit updates.

One of the things I did in the past was to work as a documentation specialist

Wolfmont, if you care to submit good solid documentation for each addon, I'm sure the authors of those addons will be eternally grateful to you for saving them the trouble.