Re-opening an old thread here, but I remembered reading this and just searched it out.
(Er, Google Groups continually errors out when I try to actually reply on the thread -- to be clear, it's here: http://xrl.us/bebz84) Did any semi-formalized documentation guidelines arise for official docs from Graham's and others' extensive work on them for this release (say, for instance, avoiding second-person, which bugs me too)? I know that Graham put a lot of thought into these matters and I'm not sure if more discussion took place outside of this thread, prior to a sprint, etc. There's an old guidelines doc in Confluence (and obviously existing since the late Trac wiki days) here, but it's barely relevant at this point: http://wiki.pylonshq.com/display/pylonscookbook/Documentation+Guidelines This just came to mind as I've been working on QuickWiki. I don't want to hold that up any longer as I believe it's one of few things impeding release, but it became apparent to me that it'd be nice to have any notes that resulted about preferred style -- or perhaps to revisit the subject in the context of this thread. Since additions and corrections to official docs will henceforth presumably be arbitrated by repository rights instead of wiki ACLs, it would be useful to have a spec that contributed doc patches must meet. Just opening discussion. -Ches On May 18 2008, 8:18 pm, Graham Higgins <gjhigg...@googlemail.com> wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > On 17 May 2008, at 19:13, Graham Higgins wrote: > > > Ben recommended folks to get familiar with Sphinx. > > When using Sphinx, perhaps you could keep an eye open for inexplicable > syntax-highlighting failures. There are a few on this page: > > http://bel-epa.com/pylonsdocs/models/sqlalchemy.html > > e.g.http://bel-epa.com/pylonsdocs/models/sqlalchemy.html#testing-your-models > > has an apparently correct "code-block:: python" directive but the > syntax isn't highlighted for python. There are a few other examples of > similar failures to syntax-highlight on the same page. > > I've also seen the same (apparently arbitrary) failure to syntax- > highlight for other languages (n3 and sparql). > > Cheers, > > Graham > > -----BEGIN PGP SIGNATURE----- > > iEYEARECAAYFAkgw1YAACgkQOsmLt1NhivxqrgCeKu5BAARlknlOvu+HjE1FU5qs > ZRkAoLMRBX5hFphQ//uRu8b1aqH/jxppiQCVAgUBSDDVgFnrWVZ7aXD1AQK6mAP+ > NhioYiskgHZhDpxYv2TWnPIOVtzlGYYRMzsIvRuglUB5hn+KLe48L0qZJNf3njJ3 > 3tkHJDlOOu6glskV1HHu73yf7HOhPlnooCeIGMqnbY88gG7qZj+ClXD1LYRrRkN7 > 0n6RDjfbGWLJ/8PRYtIUdP82SUIh16ulD02e41nWx9U= > =aTL+ > -----END PGP SIGNATURE----- --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "pylons-devel" group. To post to this group, send email to pylons-devel@googlegroups.com To unsubscribe from this group, send email to pylons-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en -~----------~----~----~----~------~----~------~--~---
