Newbie Impression: Technology-A+/ Docs-D
Brought to you by:
nileshd
Menu
▾
▴
I am a weak programmer, i'm primarily a psychologist.
I've been looking for an open source PHP dev app and am extremely impressed by pcg technology, but the documenation is, to be honest, almost non-existent relative to how sophisticated the app is.
The hard truth is I don't think anyone will use something they can't understand.
Here are some of the things I think are really needed badly"
1) The very sophisticated PCG framework outlined in the diagram has to be very clearly but simply linked, in clear writing (preferably hyperlinked from the objects in the diagram)
to :
a) The on-screen controls of the program
b) what underlying generation modules those controls adjust
( file and/or proc names)
c) The generated filenames types to which each diagram object corresponds.
--For instance,
----which onscreen menu items control generation of "DAO" -----objects?
-----How can you scan for DAO files in a directory? Ot if they are procs/object in a conglomerate file, what is the specific header so one can scan the file and lok for them?
-----There need to be extensive examples, again, linked back to all the previous components mentioed, so the whole explanation has clear conceptual vertical integration: from working program->sourcecode standards-> generator controls->object concepts--. overall pcg project goals.
A user needing to learn HAS to be able to navigate verically through the functionality; as mentioned above in respect to DAO objects- as well as horizontally, for example across the different generator controls in the interface.
-and so forth for ALL the other objects in that starter diagram.
Without this and much more, the wonderful technology of
this invention will not be utilized by even 1/4 of the potential users- people whi want to create working apps without thousands of hours fiddling with syntax details.
It;s important to relaize that ther is a certian audience for this type of application,- many, many programmers DON'T WANT to be efficient- I've met many that would rather take
2) CRUD needs to be elaborated on, not as "boring" but as an important starting point- in the sense of some suggested goals for plug-ins, ones that will enhance realworld demands- for instance an INVOICE object generator; that has the master-detail functionality built in, along with totalling the numbers in the details.
I am not just criticizing, I am willing to help and consider my self a very good person to do so because I am NOT a strong programmer. If I can get to understand it, I can make it very clear and easy for others.
Pluses:
1) Simple installation allowed me with only very basic knowledge of php to install in less than 3 hours
However, as someone who is spoiled by using Mac SW
The sourceforge message editor seemed a little flakey-
what I was saying is that many,many programmers DON'T WANT to be eficient- they LIKE TO PLAY in all the details wasting endless, endless time. They don't wnat to use a generator, because they suffer from the "not invented here" syndrome. So THOSE people , many of the most "expert" programmers, may not be potential users. But there will be many, many people who do NOT want to waste time- and those people will not followup wioth this program without real, professional level documentation
Let me know if I can help!
Alan C
Hi Alan,
Sorry I just saw this post. Usually for the help forums, i get notified for new posts. This forum did not have the new message notificaiton enabled I think.
Thanks for the feedback. I know my docs suck :) I am more of an engineer than a writer :) Hence, I do what comes more naturally to me. I am trying though to do documentation as much as I can. I prefer though to spend the limited spare time I have on doing more development. I agree though that without docs, the product is not of much use if one dont understand how it works and what it does.
I have released an intro document to the PCG framework a couple of weeks ago at
http://phpcodegenie.sourceforge.net/docs/PCGFramework.pdf
Please let me know your comments on it and if the document will appeal to the non "expert" programmer.
I still need to do more about how to use the application itself. If you can help in any ways towards that or anything else, it'll be greatly appreciated. I put my software in open source so as to get community support and for the software to grow, but so far, has not gotten much community support. Most people seems to love more to get than to give :) So, any kind of help, be it in documentation, development or anything else is more than welcome !!
Thanks,
Nilesh
As someone who has just found phpCodeCenie, but has written code and docs's for many years,
1. writing docs is hard work, and no-one likes to do it.
2. it must be done to be really good
3. programmers can write a 'principles of operations' or technical manual that works.
4. users (i.e. not the progranmmer) needs to write the users manual to make it useful. But once it is written, please pass it by the programmer / technical folks, so they can make sure it isn't saying something that is not so. The programmers need to also be 'forgiving' about the documenters not saying it 'technically correctly'. The idea is to communicate the idea!
With all that said, anyone want to take up the mantle to spear head a users manual that will be a great as the software?