2008/10/1 Greg Beaver <[EMAIL PROTECTED]>: > Elizabeth M Smith wrote: >> [snip] >> >>> Many of us - 'documentors' - (if not all) are programmers and used to use >>> CVS and other versioning system. But this takes some extra time that IMHO it >>> shouldn't. If you want to "spread the word" and get lots of people to help >>> in docs, I believe this kind of thing that Launchpad uses is a go. I'm very >>> well aware that this takes time and not every contributor may actually help >>> with good docs, but it could be moderated. >> >> [snip] >> >> 100% yes - the initial hurtle to getting new people writing docs is >> teaching them docbook and cvs. You can whine all you want about "how >> easy it is" - but it is NOT a zero learning curve and there are no good >> (free) docbook tools on the systems most people use on the desktop (yes, >> I mean Windows - and no people are not going to switch OS's for docbook >> tools). Writing in XML is not a natural thing. An online interface >> where people can edit docs would seriously boost people helping out. >> Why do you think there are so many user notes in the PHP manual ;) >> However...you will have to wade through the bad docs too. And I have no >> solution for dealing with the "three million tools" issues. > > Hi, > > I think Hannes was also talking about the fact that committers to CVS > are not using [DOC] in their commit messages. > > I agree with Liz's appraisal of setting up docs for documenting. This > could actually be solved with a minimal VMWare appliance that is > pre-setup with everything we need to do the docs (not sure how hard that > is to do). VMware works great on windows and the version we would need > is free. > > An online interface would be useful, but would it really occur to the > developers committing to php's cvs to use it? I'm not so sure. It > takes me almost as long, sometimes twice as long to document the things > that I write, this is the main problem from a coder's perspective: free > time. I would almost rather have short summaries inside /* */ of how > things work close to the lines that implement them, it would make it > easier to debug other people's code as well as make documenting small > changes easier. Big changes perhaps should be documented with either > quick README.DOCUMENTING files, or some other quick-and-dirty situation > in the source repo for those who are not yet comfortable in docbook, or > in English (as both native and non-native speakers can attest, it's hard > to translate PHP into English :). > > This was done with namespaces, and it made documenting easier, right? > > Greg >
Hi, I know I'm a small voice here, but try to follow my reasoning. The core devs write C code. The compile C code. They test it. Now, in my mind they are going to be using PHP code to test it (yes?). So, these "tests" are the best documentation you can get. They show you HOW it works, not from the internals perspective, but from the userland perspective (how do I use this function/method). Having to test it works requires an understanding of how it works. So, MAYBE, the core-devs could write userland code examples. Covering all the methods/parameters. I'm SURE (ahem) they already have this otherwise, how do they know there code works. A few additional comments to the code would help everyone. Not reams like I seem to produce on such a small topic (I'm wordy, get over it). I'm not talking about code coverage or unit tests here, they serve a different function. Knowing how your code will behave with broken data is one thing, but making sure it works with valid data is just as valid test. Is there a way to get just examples for all the functions? If the core-devs tests are good enough to make sure the code works, then it should be good enough for users to work from. Richard. -- ----- Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 "Standing on the shoulders of some very clever giants!" -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
