Suggestion for manual

[sissy]

Hi, Bruce...

Here's a suggestion for the manual. It needs to make it absolutely clear that whenever you make any changes to the categories, related categories etc. (INCLUDING importing your database from an earlier version) the administrator MUST run the new "Update Category Path" option from the admin menu.

In my case, I did a manual database cleanup and conversion involving several hundred categories and several thousand links from my old version (v3.1) to 5.4. It took days to figure out how to get that conversion done absolutely correct so I could directly load (using MySQLDump and MySQL import) my converted data into the v 5.4.0 database. I had several custom data columns that contained data I didn't want to lose and other important conversion-related issues to consider too. So I knew from the beginning that the built-in standard export and import just wouldn't work for me.

In the end, once everything had imported without errors and I had all my categories and links in place, I discovered I could ONLY see the TOP-level categories. None of my lower-level categories were displaying at all. It was as if all my categories were defined as "invisible" (or more correctly NOT "visiable"). Frankly, I spent hours trying to figure out WHY that was happening.

I checked the visible flags in the category table and they were all fine. I checked the parent child relationships between categories and they were all fine too. Eventually, I went step-by-step through pretty much everything and it all looked good. I even spent a couple of hours wandering through the code and could find nothing there that seemed likely to be the cause of my problem either. Yet my categories below the top level were STILL not displaying!

In the end, in total frustration I sat here wondering what to do next and wandered over to your forums to see if anyone ELSE had ever had this problem and that's when I noticed stockat's post. When I realized stockat had suddenly found the solution to his problem while working in the control panel (but hadn't said what his "solution" was), I went back to the control panel menu stared at it for a few minutes until I FINALLY spotted that new "Update Category Path" option at the very bottom of the category menu.

So, I tried it. What the heck, I had NOTHING else to try and very little to lose. And PRESTO... my problem vanished in the blink of an eye!

Obviously, that "Update Category Path" option is completely NEW to ALL of us who are upgrading from an earlier version; but it is a VERY important one.

Please make sure your manual prominently explains what part "Update Category Path" plays in making the new categories appear and the portal work as it should!

Thanks!

[Bruceper]

I moved your post to an appropriate forum, it didn't really belong as a reply to an unrelated thread.

I understand that things need to be clear, and the manuals that I have written already I feel are very clear and to the point and even border on talking down to users by the implication that they have no clue as to what they are doing.

That's not my intent, but if that's the way it must come out then so be it. I feel that I can't *****foot around and be 100% politically correct when it concerns something a user MUST do or the site won't work.

For example one of the items I have listed says (for option - setup)

You cannot enter a blank (empty) value in "Additional categories pricing factor" or you will break your site. Do NOT leave this line blank. You MUST enter a 0 (ZERO).

Now that's talking to people like they have no brain, but some people need to be told like this or they will leave it blank and it will break their site.

Honestly the manual is being written for the lowest common denominator which is the absolute newbie. Anyone more experienced than that may learn things from it, but might just feel insulted.

And you're right, updating category paths is extremely important, just as updating links counts is as well if you want your site to display properly. I will ensure that it is as clear as day that any time a user updates/changes/adds/deletes a category that the instructions say "you MUST now update your category path" and if I do it all right, the text for "update your category path" will have a hyperlink to a different part of the manual explaining why they must update cat paths and how it is done.

There will be hundreds of cross links within this manual, so that a user can have everything explained to them.

[sissy]

For the record, I posted my reply to the other thread because the reader was left wondering and mystified about what Stockat did to solve his problem and I figured it would help others (and prevent future support questions for you on the same topic) if they could see what he'd done to solve it. By splitting off my post, you left the mystery open. So I'm at least gonna go back and add the answer; so others know what he did. That should save you a bit of work.

From what I've seen, I'm totally confident of your ability to write this manual, Bruce. And have no reservations that it will be a good one. As a tech writer of many years myself (with several pubished computer books aimed a total beginners in my background), I can spot a great doc writer a mile away. You do a fine job. That's why I read your install manual so darn carefully. I know only too well that reading and following a well-written piece of documentation can save many hours of frustration AND recovery.

I just wasn't sure in this particular case that you'd managed to figure out what it was that stymied stockat and like the typical user who thinks he's the ONLY one who has ever had a specific problem he never did say how he solved it himself. But I'd bet $10,000 it was that "Update Category Path" feature. That's sure what solved the same problem for me. So, I figured I'd use my manual suggestion to you to explain how he did it and kill two birds with one stone.

Anyway, you're doing a great job, guy. Thanks for what you do. It's really NEEDED! And now, I'm gonna go back and post a short answer on that other thread.

Happy New Year!
Greg

[Bruceper]

I understand now, thanks for pointing that out.

As a point, the categories should still show up in the admin panel even though update category path has not been run. At least the top level categories should anyways.

And thanks for the kind words. I don't think it's going to turn into a career, but a paid job once in a while I don't mind

[sissy]

Done! I made it a point to use every adjective I could think of to describe the phenomenon in the hope that everyone else who has this problem will be able to find that post. "Invisible", "missing", "disappeared", "vanishing" and "not visible" all got used in close proximity to categories in my post for a deliberate reason. .

And yes, you're right. My top categories did show in the search engine but nothing else did. Later I realized that in the admin panel most places where category dropdowns should have appeared (except in the category editor) were simply blank. Remember, in my case I imported directly into the category table using MySQL because of my custom column data conversion considerations. So I never used the built-in import or category edit functions at all before I encountered this problem.

One last thought... Tell Dody the "Update Category Path" option really ought to be directly BELOW the "Edit Categories" option in the menu and not 5 or 6 items away from it. Users would be FAR more likely to make the obvious connection that way...