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 -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
