Re: Documentation for SVN extension

Philip Olson wrote: > Welcome to the documentation team! I went through your patch and > nitpicked every little detail in an effort to help you (and others) > write almost perfect commit worthy documentation. Most are small > problems that come with experience: Thank you for the detailed and helpful comments. I will be fixing them promptly. > - Use example.com for all example urls I did it for one and not the other. Will do. Does everything need to be anonymized? (I literally took my own repository and copied over the output) > - Whitespace is always one space, not two I need to keep a close eye on this, since I don't use vim or emacs and my editor is set at four spaces. Nonetheless, I can't find a spot where I used two spaces. Could you point it out for me? > - Put all URLs in global.ent before commit Heh, even put that in a TODO. Antony feels that I shouldn't need a CVS account if I'm just contributing documentation for this extension, so if I'm submitting a tarball of the svn directory, where should I put the entities? In a patch? > - functions.xml is autogenerated, do not create/commit it > - First use scripts/xml_proto.php to generate skeletons for all functions Argh! I wish I knew about this script earlier! :-) Will do. > - Fix <title>Subversion &Functions;</title> Not sure what you mean. Do you prefer Subversion Functions without the entity? > - Remove comments like <!-- Example: Optional parameter --> Okay. I'm keeping them there for now to help remind me of some docbook structures, but I'll comb through and delete them once I finish. > - In theory, new documentation is formal (no 'you') > The part about formal (not conversational) text is a bit idealistic as > few follow this but slowly we're talking about it, and trying. Oh, no problem. My writing style uses "You" profusely, but other than that, I have no problem writing formally. -- Edward Z. Yang Personal: edwardzyang@thewritingpot.com SN:Ambush Commander Website: http://www.thewritingpot.com/ GPGKey:0x869C48DA http://www.thewritingpot.com/gpgpubkey.asc 3FA8 E9A9 7385 B691 A6FC B3CB A933 BE7D 869C 48DA