Xataface Forums

Posted: **Tue Jun 05, 2007 10:32 am**

I received a message from someone today who has issues with the Dataface documentation:

"OK, I guess some explanations are in order." I would say so.You definitely get an E for effort; but you of course know what that gets you at the University level. It is a shame you spent a tremendous amount of time and verbage telling us how easy it is, without understanding that you descriptions are about as clear as mud. I feel so sorry for you. The time you must have spent writing this. But, you are talking to your self. You may have sent a message, but nobody received it. After 30 years using computers and 15 years using and designing web applications, I give up.

I believe that he was referring to the Getting started tutorial at http://framework.weblite.ca/documentation/tutorial/getting_started .

The language of this email indicates that the user is frustrated at not having success in getting his application running, but I am curious if others have had difficulty understanding the documentaton also.ÃŠ Particularly the first few sections of the Getting started tutorial.

I would like this tutorial to be as "easy to understand" as possible so all suggestions to that end are welcome.

Thanks

Steve

Posted: **Tue Jun 05, 2007 1:18 pm**

Hey Steve.

The getting started is just fine for your complete "not-a-programmer" like myself. I was able to go through vocab lists, access control, and the like without a problem. I will say that there are times that I feel the documentation (how-tos really) assume a certain level of programming competency.
It also seems that there are a lot of features that are not documented, E.G. version 0.7 seems to have a lot of functionality that may not be documented, or if documented, is not easily found. I finaly found good info on my problem getting portraits to display under Detail View under an article called "How to handle file uploads." (Sorry for not RT*M before posting on the Forum.)

A perfect example is the Import Filter how-to goes waaay beyond what I would need immediately. I remember thinking, how about a simple "here is how to import a simple CSV file" paragraph? It is difficult for me to take the given example and work it around for doing just the CSV.

The Getting started info seems to me fine as-is. I would like to see it expanded with more examples for more of the current features, and perhaps targeted to more of a novice audience in the How-to articles.

Okay, that's my two-cents worth. Your mileage may vary.

Regards,
Bob

Posted: **Tue Jun 05, 2007 3:39 pm**

Hi Bob,

Thanks for the feedback.ÃŠ I have tried to add some structure to the how-to's to make it easier for people to find what they are looking for.ÃŠ I have also added a categorization by audience (Beginner, Novice, Advanced) so that users can prepare themselves for the level of the how to.

The idea of a simpler example for the CSV importer is a good one.ÃŠ I added a smaller example to the Importing how-to to try to make it less of a learning curve.ÃŠ The previous tutorial was done rather quickly by copying and pasting from an existing project, so that I could get something up for my developers to refer to.

Best regards

Steve

Posted: **Wed Jun 06, 2007 5:28 am**

Hi Steve,

When I came here for the first time, I looked first at the presentation then at the documentation. I was impressed by the video, then by the tutorial so clear : so I adopted DF.

I think that everyone could participate to the doc. It is possible to create a document on a subject, that is great!

What I'd like is to modify or to add some precisions in the tutorial, we need more examples sometimes. Then the modification would be validated by the author.

We see this problem in every open source project : the development is more rapid than the documentation because we need more volunteers to understand, experience, then communicate clearly about it. This is not easy, but you succeed in this enterprise like zopemgr and others...

We could use the forum to extract doc and modify it to insert it inside the documentation for example.

Myself I am far from being an expert but I could put information into "well-formed" text, adding explanations, examples...

Jean

Posted: **Wed Jun 06, 2007 10:42 am**

Thanks for the feedback Jean. Certainly help with documentation is appreciated. The documentation section is set up in such a way that anyone can add their own how-to documents, or tutorials. I have also just enabled "Comments" on the tutorial and how-to pages so that users can add their own comments, feedback, and code samples. These sorts of comments are a large part of why the PHP documentation is so good.

Steve

Posted: **Thu Jun 07, 2007 1:06 am**

Hello Steve,

Thank you for this possibility of comments. I'll use it as soon as I see precisions to add. May be you could do it for the manual as well.

As developpers, we are mainly pragmatic, sometimes we search for something, we navigate a bit, we find it in the forum or we try someting that works, and we see it could be added in the manual or elsewhere and we do it at this time. If we don't at once, then we forget it.

So it is great to use so that it can benefit for all.

Kind regards

Jean

Posted: **Thu Jun 07, 2007 10:11 am**

Comments are now enabled on the reference manuals too.

Posted: **Fri Jun 08, 2007 4:40 am**

I received a message from someone today who has issues with the Dataface documentation:
"OK, I guess some explanations are in order." I would say so.You definitely get an E for effort; but you of course know what that gets you at the University level. It is a shame you spent a tremendous amount of time and verbage telling us how easy it is, without understanding that you descriptions are about as clear as mud. I feel so sorry for you. The time you must have spent writing this. But, you are talking to your self. You may have sent a message, but nobody received it. After 30 years using computers and 15 years using and designing web applications, I give up.
I believe that he was referring to the Getting started tutorial at http://framework.weblite.ca/documentation/tutorial/getting_started .
The language of this email indicates that the user is frustrated at not having success in getting his application running, but I am curious if others have had difficulty understanding the documentaton also. Particularly the first few sections of the Getting started tutorial.
I would like this tutorial to be as "easy to understand" as possible so all suggestions to that end are welcome.
Thanks
Steve

As someone with a programming background, but limited PHP skills, the intro allowed me to set up a database pretty easily. There are bits I can't do easily, but they relate to a lack of application on my part and a lack of knowledge of PHP. Yes, the documentation could be bigger and better, but this isn't a commercial product, the forum works very, very well - and we all, including you Steve, have a day job.

My advice to your emailer is to use the forum, and then - as you have suggested elsewhere - provide upgraded documentation where needed.

Posted: **Fri Jun 08, 2007 4:59 am**

Comments are now enabled on the reference manuals too.

Thank you Steve. Ooops I realize that i forgot a smiley ;=) in my post...
Jean

Posted: **Sat Jun 23, 2007 5:35 pm**

I have been developing web sites for about 14 years but I am NOT PHP programmer. I did have some problems understanding how to actually start because I could not even find in Docs what URL to put into browser to get started from scratch. "STEP ONE"

I resorted to the forum for some boot strap help on the first step to get past a blank white screen.

I also installed the webauction application which was my target application in the first place. But could not figure out from documentation to open an existing application (webauction) with the dataface application so I can edit it.

I often am asked to help others use their computers and at first I was told I assumed they ( customers ) knew as much as I did...which they do not. These days I am complimented when I go to help someone with a computer issue because I have learned to talk "english" that someone with little experience can understand.

This is often a problem with documentation written by the developer in that they often write as if they were talking to themselves and, of course, everything is very clear in their minds. I think documentation is best written by a third party who is less educated but has mastered the application.

This is my first time with dataface and it looks like it has a lot of potential to be a great application for me to use once I get the hang of it.

First experiences with the author are that he is very responsive and open to discussing all aspects of his project.

I look forward to some easier "novice" docs with actual step-by-step lessons starting with a blank browser.

Kudos.

Posted: **Sun Jun 24, 2007 7:35 am**

Paul

Could you provide the novice docs as you progress? I am sure Steve would be very appreciative.

Neil

Posted: **Sun Jun 24, 2007 1:54 pm**

I will try to add that to my "TO DO" list. *smile* I have no problem sharing knowledge !
Will not be FAST because I have to learn first!! and time is a premium right now. (trying to sell a house and move about 350 miles north and take business with me)

Posted: **Sun Jun 24, 2007 2:08 pm**

I could not even find in Docs what URL to put into browser to get started from scratch. "STEP ONE"

This is located in the README.txt file for dataface.

Thanks for your thoughts on this Paul. Please leave comments in the getting started tutorial where you think there may be better instructions. The getting started tutorial is designed to be the place where you learn "from a blank browser" how to set up an application.

Posted: **Tue Jul 03, 2007 4:50 pm**

I just have come across this package. To be honest, I have looked through a bunch of similar products, but I couldn't find what I was looking fore. One of my major concerns was the documentation, there are some products which do just the same (on paper/screen), but no way to figure out how. I decided on DF based on the amount of documentation it has. I'm not saying that it cannot be improved, but it is a great start. I have some knowledge of PHP, MYSQL and HTML, but I would not consider myself a good programmer, and it all made sense. Where I would see improvement is more examples. It was very helpful to go through the existing ones and see how it works and how far I can stretch DF. You might not be able to provide free code for other sites, but I think it would be a great idea to collect a list of sites which use DF. To see the work in action gives me lot's of ideas on what it is I could do and how.

Tamas

Xataface Forums

Documentation clear as mud?