upgrade problems / instructions need to be clearer

gracestanat

I'll start with my questions in case people don't want to read the rest:

-How do I upgrade without losing my descriptions?
-How do I backup my database?
-What do I do with my .htaccess file? Put it back where it was?

--

Now on to a more sweeping topic. I've said this kind of thing a few times, and I usually receive a minor flame in retaliation, but I will try again.

ZenPhoto rocks. Period. The people who work on it rock even more. Double period.

The part of ZenPhoto, however, that does NOT rock is documentation. As a web design and application developer in other spheres, the excuse of "we're changing it so often that we don't have time to document it" is, frankly, somewhat lame. It may be boring, but documentation is a KEY part of getting more users and thus increasing the mass of the ZenPhoto community.

The fact that one needs a guide to read the User Guide, and that guide is STILL difficult for the layperson is a good example of this, but I digress.

My current wrestling with an upgrade is a good example. I tried to use a nightly build to fix a recent bug in 1.2. The instructions on the home page of ZenPhoto are... well, cryptic at best. (I think they've also changed over the last 24 hours.)

In step 2, it seems that you're supposed to throw away your themes folder. I'm assuming that's not a great idea if you've downloaded extra themes or created your own. So I saved my work. This might seem like a no-brainer, but the official instructions seem to advise one to do otherwise.

In step 4, it is not clear what you are supposed to do with .htaccess. I kept a copy, but if I follow the instructions in step 2 (at least the instructions that were on there a day or two ago), I would have just thrown it away.

I think there used to be a note about backing up your database, but that's gone now. And it isn't clear how to do that anyway.

So after doing my best in the upgrade, I seem to have lost all comments and descriptions. Fortunately, I'm still just messing about with things before I really upload, but if I had been farther along, this would have been a bummer.

So my plea is the following:

-Can someone knowledgeable write a good cheat sheet for upgrading? Ideally this is someone who doesn't have the viewpoint that non-programmers can just jump in a lake if they don't understand complicated directions.

Again, in case it is not completely clear, I think that the product is great, and the people who have worked on it are also great. So please don't take offense. As an experienced entrepreneur, designer, and developer, better explanations are ZenPhoto's low-hanging fruit! It's the easiest way to make the community bigger and better!

sbillard

The excuse for the documentation in the case of zenphoto is that there needs to be someone to volunteer to do it, just the same as that there needs to be people who will volunteer to do implementation. I've said this before in response to the documentation rant, but so far no one from the community has stepped up.

There is lots of information within these forums that could be turned into good documentation if there were someone industrious enough to sift through it. But if no one does, the documents you get are the ones we choose to write. Remember, we developers know how to use this product, so documentation is not so important to us.

So, let's get down to the details:

Step #2 says to `Delete your old copy of the zenphoto files.` Now, some will take this to mean to delete anything at all on your site. But remember, we tech types use words to mean what they say. The long hand of this: delete the files that came with the old copy of zenphoto.

Step #4 how shall we say this. It says `Make sure .htaccess is writable`. Would you prefer we streach out the sentence to `Make sure that the .htaccess file can be written to by zenphoto`? That doesn't really say anything different. How would you want this worded?

Backing up your database It does not say anything about backing up your database. Nor does it say to backup your images. Or to backup anything else. Those are your personal choices. As to how to do it, that is also a choice you have to make. Your ISP may provide backup capabilities. If you have installed on your own computer use the same backup process you do for your other files.

So, why don't you write this guide? You have the correct viewpoint. You can get answers to your questions here on the forum. If someone like you does not volunteer to make these documents then the doucments you see are what you get.

gracestanat

I will certainly consider writing the guide. To be perfectly honest, I am evaluating whether or not I think I'll get the support I need to write the guide. Since I am not a developer, I will need to have questions answered and other support from folks that are closer to the product in order for me to do a good job. I commend you on your efforts so far, including your efforts to answer my questions. Understand, however, that not all the developers are so inclined, and sometimes it is an uphill battle to get a clear answer out of people. Like many people, I have limited time and other commitments, so I am simply trying to determine if 1) taking on this task will be a supported maneuver, or a frustrating one, and 2) on a personal note, whether or not I have the time to do so.

In response to your explanations:

step 2: I *think* I understand now, however since I used a SimpleScript install, it's not clear to me what came with the first version. Perhaps it would work to say: delete anything that has a new version in the nightly build. Not sure. As a programmer, you can appreciate that while you may have intended to say something exactly correctly, it might still be ambiguous. Without specifically defining what you mean by "ZenPhoto files," the rest of the instructions become more vague.

step 4: Well... I must admit that I still am not quite clear on this. Are you talking about the privileges on that file? Or, to be more direct, HOW do I determine if .htaccess can be written to by ZenPhoto?

Still wondering:

-Should I put the old .htaccess back where it was since there is not a new one with the nightly build?

-Is there a good place for me to learn how to back up my database?

-Why do you think that I lost the descriptions? I would assume those are stored in the database which I believe I successfully reconnected based on the dialog boxes that occurred during setup.php.

-The thumbnails still seem to be broken, but I'll address that in the other thread we're having.

Thanks again for responding and hopefully this communication will lead to something useful for many peeps.

acrylian

I second that I also welcome if you would like to write or rewrite the guide for that. Remember that we are also volunteers with other things to do (I am actually also not a full blooded coder, just to note).

You can always ask here on the forum. You seem not to be around here that long otherwise you would know that we use to give a lot of support, even for things that are not always dirctly related to Zenphoto.

Some explanations to your further questions:

Step 2: I agree that could be clearer.

Step 4: Yes, that means the privileges of the file since Zenphoto will try to change it on setup (adding hte correct path etc).

Should I put the old .htaccess back where it was since there is not a new one with the nightly build?
Actually no need to do since there is always one included in Zenphoto, even with the nightly (it may be invisible on your computer as it is on Macs though). In case you made some custom changes it is of course a good idea to backup them and add them later again.

Is there a good place for me to learn how to back up my database?
I don't know any good place, but the MySQL site would be surely a good start. Also you probably have phpMyAdmin on your webspace to manage your databases, which can be used to export your database, too. And additionalyl your ISP may have a backup solution, too. I suggest to contact your ISP first.

Why do you think that I lost the descriptions? I would assume those are stored in the database which I believe I successfully reconnected based on the dialog boxes that occurred during setup.php.
If you used the same database and do not change or removed the albums folder that should not happen. Zenphoto is filesystem based, if it does not find the images in the database on the filesystem they would be cleared from the db.

sbillard

The most likely reason for your loss of descriptions is that the database prefix you used for the upgrade install was different from the one used on the original install. Your descriptions are not lost, just not connected to the installation.

You can browse your MySQL database and see what tables there are. The Zenphoto tables will normally be prefixed by a common identifier, so, the albums table would be zp_albums, etc. You can look in the zp-config.php file to see what the current prefix is. Change that to the old prefix and everything should be back. (Of course, if you have added anything since installing the upgrade, that would be lost.)

It is always much better for the documents to be written by someone other than the developers. And that is not just because developers tend to be week on writing skills. We are very familiar with how things work and just don't see the words in the same light as someone coming new to the software.

We will answer your questions. Please take on the task and add to the useability of Zenphoto.

gracestanat

ok - thanks! a few responses, first about my specific issues and then about writing documentaiton:

database: sbillard, you are correct. using phpMyAdmin, as suggested by acrylian (thanks!), I was able to determine that I have two tables of every type, one with a "zp_" prefix and one without. Looking at my config files reveals how this happened. I'm assuming it's okay to simply erase the ones that I no longer want to use. I'm also assuming that using "zp_" is a tad bit safer and more generic (but obviously SimpleScripts doesn't do that, which is a shame). Let me know if all these assumptions are correct.

htaccess: well, i moved the file back onto the server, but it's in there as "htaccess.txt". i notice, upon examining invisible files, that the one downloaded with the nightly build is just named ".htaccess". I'm assuming the later is correct. Perhaps it was tagged by my Mac with a ".txt" when I pulled my whole site down, not sure. In any case, should I remove the one called "htaccess.txt" that is on the server now? I don't see a ".htaccess" on the server. Is that because it is invisible to my ftp program or do I need to put one back there (or rename the text file that is already there)?

--

okay, on to the more important topic: documentation.

my plan is this. i'll get my site up and running and continue to learn how to use ZenPhoto for a bit. then i'll attempt to write some documentation for common tasks/questions as time permits. some of the things i'd like to start with are installing/upgrading, what all the settings mean inside ZenPhoto, and the basics of creating/modifying themes. i will do this all from a very non-developer viewpoint so as to make it as useful as possible for the most folks.

my personal email is grace@stanats.com. if any of the developers are comfortable giving me their emails then i can email questions directly, then i think the forum is probably not the best venue for working out documentation issues. or perhaps there is a developers forum somewhere that i could have access to after i get going. we can discuss how best to post docs at a later time. thanks!

sbillard

database: Yes, you can erase the tables you do not need. The prefix is only needed if the database is going to be shared, but of course, using the zp_ prefix will protect you in the future. I am not at all familiar with SimpleScripts, so don't know what it does.

.htaccess: The Mac OS can be over protective at times. Maybe some warnings in the document are appropriate. Anyway, somehow you need to copy the .htaccess file to the server withoug renaming it. Acrylian is a Mac user. He will, I am sure, give instructions.

I've sent you a mail with my email address. Looking forward to this project.

sbillard

The mail I sent you bounced.

trisweb

Grace (is that your name?) if you want to organize some documentation, that would be very welcome. I think the best place to build the docs would be on our Trac Wiki - http://www.zenphoto.org/trac - make an account there and I can give you permission to edit pages.

If you want to ask specific questions I would say use the zenphoto-dev mailing list, which you can join at http://groups.google.com/group/zenphoto-dev . There you will have a wider audience for responses, and those who are interested in helping more with the documentation might come forward. Plus it will give those list members something to do as that list hasn't been used as much as it should.

Thank you! Sign up for both of those and you can get started.

gracestanat

sbillard - it looks like the forum added a period on the end of the email. just send to "grace@stanats.com" and it will work.

trisweb - yes, Grace is my name. strange for a guy, but there it is anyway. thanks for your advice about these resources. i have signed up for both of them and will await approval. thanks again.

trisweb

Thanks Grace - no surprise about the name, but it is useful to know which pronoun to use Looks like you're on the google group, and I'll give you permission to edit articles on trac now. Thanks again.