Documenation Ideas

[Eric Barnes]

Hello everyone.

I have been redoing a lot of our documentation and I want to make it more user friendly and hopefully have it better used.

Before I get to deep in I wanted to open a thread and see what you guys think. What should be included? What shouldn't?

Any ideas to make it better utilized? Better categorized?

[philoo]

I am discovering 68Classifieds from some weeks and I have sometimes difficulties to know how features run. Especially for Extensions or Mods...

And also especially for foreign customers that have to overcome the language difficulty barrier.

By example, I purchased the vBusershare that allow to share users between a vBulletin forum and 68classifieds. But the package does not explain how runs the extension, the required things and the limits of this users sharing. So, to discover how it works I had to post in forums some questions and wait for answers.

An other example :
I am interested in the "Rating Mod"
The only explanation says "The rating module allows users to review listings or members."

Nice. But I have to install it for discovering how it runs !
I would like to know things before hacking my scritps :
- Do we have to be registered before rating members or listing
- Can members delete ratings ?
- Are ratings moderated by admin ? if yes, is is switchable ?
- Wich way ratings appears on 68Classifieds (text, stars, etc ...)

The same for the Ad Reporting Module that only says "This allows users to report listings"
We had to ask questions in forum to discover that it reports an #ID (not a link) to the admin thru the contact form (that need to enter name, email, captcha ... before the report is sent to admin)


Some explanation lines and screen prints could help guys like me who are discovering 68classifieds secrets !

I think that all these things are obvious for Eric (Suzkaw) but not at all for new customers. The first contact with 68Classifieds is very impressive, but all these details can leave an impression of opacity...

BTW, many thanks to Eric to open this debate and thread !

[bowers01]

Most importantly you need a page that shows where to edit for certain pages.
Eg What code to edit to change the featured listings on the front page and things like how to change the text in the footer. The only problem is where do you end.

Secondly a page with how to call certain things would be good, Eg how to call extra registration fields ect.

Just my 2 cents
Nick

[domino]

Most importantly you need a page that shows where to edit for certain pages.

Completely agree.

What I'd like to have is complete information on what file controls what action/feature or page. I find a lot of it myself but it would be great to have detailed info.

This may exist but I haven't found it yet. I guess I find myself digging for things a lot. I do lots of searching on the forum and find most of my answers, but some of the documentation is too basic for me.

A BIG request would be finding some way to make a WordPress plugin for 68Classifieds.

[Eric Barnes]

The easiest way to find out everything for a page is to edit the layout.tpl file and add {debug} to the top.

This will open a popup window with everything assigned to it and all variables.

[ombre]

Originally Posted by Eric Barnes

The easiest way to find out everything for a page is to edit the layout.tpl file and add {debug} to the top.

This will open a popup window with everything assigned to it and all variables.

From the point of a develper i will agree with you. From the point of a administrator who will only add existing funcionality without making modifications on the scripts i don't agree.

[Lhotch]

What came first the chicken or the egg??

The documentation IS the code.

People say they want to know where in the code they need to make changes and to find it read the code. If you cant read the code then what good is knowing where to make changes? If you cant read the code then you are likely not capable of modifying without specific direction which usually includes what file and exactly where to modify.

If we are talking about smarty, largely all the smarty pluging are in the plugins directory and the name of the file is fairly explanatory as to what the plugin does.

For modifying templates, there are a couple very thurough documents in the forum which explaine all about editing the templates.

What happens is everyone is just looking for a quick fix but the more documentation you have the harder stuff gets to find and there comes a point where there is a lot more documentation that there is template/smarty/php code that people dont even use the documentation.

Also the question of what to document needs to be addressed. What one person sees as common knowledge another may be clueless about so do we document it or not?

Lastly the new feature request forum is filling up quick. There are obviously new features that people want, does 68C development get put on hold so documentation can be written to teach people how to use html/css/smarty/php?

As someone who often checks out other scripts I can appreciate your desire for more documentation. Ive looked at many well documented scripts and what I have found is the documentation is NEVER sufficient and always laves me with questions.In the end there is no substitute for spending the time learning how the scripts all work together.