Page 2 of 2

Posted: Thu May 11, 2006 9:24 am
by Chris Corbyn
Everah wrote:The easier to understand, the better. Even if there are different types of users, if you can reach the most comuter illiterate grou of users, everyone could feasibly stand a chance at understanding your. It is tough. I know. I have been writing user guides for some folks at work that I think my 5 year old daughter could read and understand.And even these can go over their heads sometimes.

But I think if you target the entry level users, and if you can get close to reaching them, your docs should be golden.
P key not working? :P :lol:

Posted: Thu May 11, 2006 10:19 am
by RobertGonzalez
That is funnier than crap. :lol:

I was on my wife's computer this morning, and there are times when the keys just don't register. I guess this morning, it was P.

I suose I should roofread my osts before ressing the review or submit buttons, huh?

Doh, wait, I am on a computer that acutally has working components now. Silly me...

Posted: Thu May 11, 2006 10:21 am
by RobertGonzalez
And I suppose, to keep this thread on track, that I would offer the suggestion that when composing documentation, that you use a device that actually works properly AND that you proofread what you put down in the docs. :oops:

Posted: Thu May 11, 2006 6:03 pm
by Chris Corbyn
Thanks to this thread I'm currently going through my my latest source code adding phpdoc comments. Oh dear, I think there's going to be almost as many, if not more lines of comments than there are lines of code by the time I'm done :?

Posted: Thu May 11, 2006 6:06 pm
by RobertGonzalez
Did you know that when your code is documented using phpDoc that Zend studio picks up the comments and uses them to tell you your own function syntax? That is a really cool feature. Don't know why I brought this up. I guess I just thought it was a cool little feature.

Posted: Thu May 11, 2006 6:24 pm
by alex.barylski
d11wtq wrote:Thanks to this thread I'm currently going through my my latest source code adding phpdoc comments. Oh dear, I think there's going to be almost as many, if not more lines of comments than there are lines of code by the time I'm done :?
Here's a tip...

Comment like crazy...but on anything more than a line or two use multi-line comments...

That way people who hate looking at zillions of comments can hide them by using an editor which supports source folding and/or recognizes /* */ as a code block...

UltraEdit does and I use it like mad because as much as I comment I also hate to look at what I already know :P

Cheers :)