> > "This function is only available in CVS. " > > i dont' understand the sentence above. [snip]
> This illustrates a point I've mentioned before. Speaking as someone > who spent 10 years or so as a technical author/editor, I very much > think the term CVS should be banned in end-user-oriented documentation > (including the bug-reporting system!). If someone has never come > across a version-control system before, it can be very off-putting to > be confronted with this "geekie" acronym -- even I, with over 25 > years' experience in the industry, found it confusing the first time I > came across it, and had to go and look it up in an online glossary. The term CVS is rarely used, except for those functions that are only available in CVS. The above <note> that mentioned CVS shouldn't have been written, versions are kept track of automatically for each function. How about instead we use, for example, the <acronym> tag (or similar) so: <acronym>CVS</acronym> And in acronyms.xml we would list a definition for such terms. I don't know if <acronym> is the appropriate tag but the idea is what's important here. I prefer this method. Avenger is translating english to chinese, he knows what CVS means but wasn't sure about the context. I blame the note, which shouldn't have been there. But of course your point is valid. > Wherever possible, the term "CVS" should be replaced with a phrase > like "current development version" -- this gets across the idea that > it's not in an officially released version, but will (Should?) be in a > future one that's currently being worked on. Perhaps it would also be > useful if this phrase could be made a link to snaps.php.net...? This is an interesting idea. One reason to use CVS is so people will know it's in CVS so if they require the functionality they can download/use it. I'm -0 on this change because people should learn what CVS is, and it's shorter :) And +1 on a definition system like the <acronym> idea proposed above. > There's some other terminology used in various places that's rather > "techie" and I'd like to see replaced with a more plain-language > description -- when (or perhaps that should be IF) I have some spare > time, I'd like to identify these and put some proposals to the list. > (And, yes, eventually I'd like to get CVS access and actively help -- > I'm especially interested in the structured argument lists and > CHANGELOG proposals that are currently being discussed.) Please list a few other terms, I'm curious. Sometimes these techie terms are important and if people don't understand them they shouldn't use the function! Of course I'm being a little conservative on the idea and can only offer my opinions on a case-by-case basis :) I look forward to your CVS access to the phpdoc tree and hope spare time finds its way into your life and into the php manual. Regards, Philip -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
