-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On 17 May 2008, at 22:21, Ben Bangert wrote: > On May 17, 2008, at 11:13 AM, Graham Higgins wrote: > >> Ben recommended folks to get familiar with Sphinx. >> >> Which I have been doing. I've been amusing myself with >> http://bel-epa.com/pylonsdocs/index.html > > Are there pylons-dev patches coming with some of these changes? :) That's the basic plan. Anything that is ultimately considered to be an acceptable contribution can be pushed back as patches. I'd like to stress (and I regret not making this explicit in my original post) that the work is merely a highly personal scratchpad for i) exploring the use of using sphinx in the context of generating Pylons docs and 2) exploring some different ideas that I have about the document's structure, form and presentation. I should also stress that the unappealing colour scheme was selected quite deliberately in an attempt to reduce the possibility of my scratchpad being mistaken for the official docs by people who might encounter the URL out of context. > I realize parts are the official docs, which I assume you have in > there to try them out? Yes. That was my reason for including them. I needed to work both top- down and bottom-up simultaneously as I wanted to get a sense of how a fully-populated document might hang together in terms of structure and flow of concepts. I added the "design" elements in order to make the rendered document appear superficially complete and to explore one or two other ideas informed by principles of cognitive ergonomics. Specifically, I wanted a graphic prefix for every major heading in order to gain a stronger visual separation of the headings and I also wanted to lend a distinctive visual appearance to each major section (of the MVC triumvirate, at least) which I did by including a illustration drawn from the punned egyptian context. The illustrations will be processed in parallel by the reader, they have no direct semantic connection with the text, so are effectively information-free within this context. Their processing will make no discernible cognitive demands on the reader and they should act as visual landmarks in the document. > But the sections where you expanded on the "XXX Fill in this here" > bits are good, were those taken from the book as well? No text from the book has been included, I did not want to prejudice James' auctorial process. I've written a small amount myself but mostly it's just copy'n'paste (mainly plagiarized from available confluence docs, some from elsewhere) with some quick'n'dirty glue text and some edits to bind it together, resulting in a bricolage of fragments that present the facsimile of a complete document --- as I mentioned, I was amusing myself. > As I mentioned in my talks with James, the book itself is too large > to maintain as the Pylons docs ... After I completed this initial phase of the exercise, I found that my first question to myself was 'How does this stand in relation to "Definitive Pylons"?' Thanks for answering my unvoiced question :-) > How come you didn't suggest a logo? I hadn't conceived of it as a suggestion for a logo, I merely sketched out something to do the job at a level I thought minimally adequate for my purposes. If you feel the notion has some merit, I have no objection to it being picked up and developed further. I could contribute a production version of the hieroglyph in both rasterized and vector versions if required but I'm also quite relaxed if someone else is keen to make that contribution. > One of the reasons Phil and I passed on most of the logo suggestions > was they were a bit too 'flashy'. Reconsidering an Egyptian based > theme after we've followed the 'power' and 'electric' themes to all > directions does give me more food for thought. The Egyptian > hieroglyph you choose is simple and memorable without me having ever > really seen it anywhere else. I had already chased down most of the connections that were mentioned in Saturday's discussion on #pylons (sorry I wasn't around to chat, I was rostered for duty at the boat club). I also found the semantic connotations to be generally favourable and the synchronicity added to my amusement (yes, I s'pose I am easily amused). I was finally convinced by this additional synchronicity (not that I place a great deal of faith in its credibility): " The Sphinx itself forms an image of the akhet hieroglyphic when approached directly from Memphis ... the Sphinx appears silhouetted between two pyramids." [1] > The Egyptian Pylon in general also conveys a theme of something > powerful yet elegant in its simplicity, which is exactly what Pylons > itself aims to be. In comparison, the electric theme leads to things > like coal power plants, generators, electrical lines (Which cause > cancer/leukaemia), or lightning bolts... none of which has the same > feel. ;) > I must say, I really like it. That's an unexpected bonus. I must admit that I didn't pick up on those negative connotations of electric pylons. I chose the hieroglyph mainly because the synchronicity amused me and also because its landscape aspect ratio suited my purposes better than the inherent portrait aspect ratio that generally accrues from electric pylons being substantially taller than they are wide. You mentioned on #pylons: "going Egyptian lends a different feel to the content as well". Apart from the obvious graphic elements, there /may/ be a couple of other, oblique elements in play here. I edited some of the text to remove the repeated use of the second-person pronoun. This is simply a personal dislike of mine that has recently emerged from reading lots of ill-written on-line documentation. I have come to view this sort of "tu-toing" [2] voice as something of an indicator of poor writing and careless articulation. However, rather than making an unsupported claim, I'm rewriting parts of the document in order to test my perceptions. I've realised that treating the documentation requires as much care as does generating tests for the code, so I'm aiming to be exacting with the text such as enforcing consistency on whether values for variables are "set", "assigned" or "bound". Essentially, I'm attempting to apply usability design as well as cognitive ergonomics principles. I also put quite a lot of thought into the selection and preparation of the illustrations. Minimally, they are intended to complement and leaven the text (I have some other, more fanciful, notions concerning them). > I noticed you got the babel module covered, that'd be great to > include in the docs of course, IIRC, sphinx has a small issue with some of the unicode in the Babel docs. I will report on it in a day or so. > also, Christopher Haas mentioned that the About section you have > would merge nicely with his. No problem, use whatever you / he thinks is appropriate for inclusion. I will continue bimble along my own path for a while yet. [1] http://www.unexplainedstuff.com/Places-of-Mystery-and-Power/The-Sphinx.html [2] http://frenchforawhile.blogspot.com/2008/02/tu-toi-faux-pas.html Cheers, Graham -----BEGIN PGP SIGNATURE----- iEYEARECAAYFAkgwprUACgkQOsmLt1NhivxhGACg8Un+/GbKoBvVkDjZ9v2AU68F awgAn0Vy5UgAgH3LCDSWQOH2s/3WVeJxiQCVAgUBSDCmtVnrWVZ7aXD1AQKffwP/ R5CIGojilAzyx74wYUsl0vgW2dckpEa9Iyh6YAJbKw6nWk5PsTbwobKifWTK0ep0 92ejEfwxk6tI6G7QqX7xvJe5KKihDjPs8qnl5B7AaKniyOO9ajrsqNsr7g2y1Ytv bhrB/Au+o5jv1maYyVS+YHiw1qPRICE7hR2Jd6yg1S8= =sYdH -----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 [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en -~----------~----~----~----~------~----~------~--~---
