Documentation

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Post 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:
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post 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...
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post 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:
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Post 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 :?
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post 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.
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Post 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 :)
Post Reply