From: Miles E. <mi...@ca...> - 2003-11-07 16:52:37
|
I've spent a little time trying to give the html docs a minimal css facelift to make them look a little less generic docbook. Please have a look here: http://www.caddr.com/sbcl-doc/ If this is acceptable I can easily put it together as a small patch. --=20 Miles Egan <mi...@ca...> |
From: Edi W. <ed...@ag...> - 2003-11-07 19:42:25
|
On Fri, 07 Nov 2003 08:52:14 -0800, Miles Egan <mi...@ca...> wrote: > I've spent a little time trying to give the html docs a minimal css > facelift to make them look a little less generic docbook. Please > have a look here: > > http://www.caddr.com/sbcl-doc/ > > If this is acceptable I can easily put it together as a small patch. A little bit too large IMHO, but otherwise nice. Edi. |
From: William H. N. <wil...@ai...> - 2003-11-07 20:57:30
|
On Fri, Nov 07, 2003 at 08:52:14AM -0800, Miles Egan wrote: > I've spent a little time trying to give the html docs a minimal css > facelift to make them look a little less generic docbook. Please have a > look here: > > http://www.caddr.com/sbcl-doc/ > > If this is acceptable I can easily put it together as a small patch. To me, "generic" is not necessarily a flaw in things, like documentation, that people use for utility, as opposed to for entertainment, or for fashion, or for other uses. To see someone writing on a similar topic (with more confidence than I feel) try http://tbray.org/ongoing/When/200x/2003/11/03/CuiBono He's arguing that for active software systems a boring user interface that's widely understood is a feature, not a bug. I feel that a similar principle applies to the "user interface" of passive documentation as well. I'd probably be willing to defer to a consensus if my opinion turns out to be in a clear minority, since I don't consider myself incredibly adept at making users comfortable in particular, or marketing-related stuff in general. But my initial impression (using the Mozilla 1.0.0 browser which came with my old Debian) is that the new non-generic approach at http://www.caddr.com/sbcl-doc/ is not an improvement for the fundamental things documentation is needed for. It does look different, of course, but I don't find it easier to read or understand. What's more -- for reasons implied by the CuiBono link above -- some kinds of "different" can easily conflict with important design goals like usability and understandability. As long as the vanilla DocBook presentation style isn't too outright wrong, it can be easier for people to find information in that style just because of its familiarity. This can show up directly -- just in people not knowing what typographic cues to expect -- and also indirectly, when people have chosen and tweaked their browser environment (font size preferences, etc.) to be comfortable for them on their display when reading plain-vanilla text, and then find that for a customized format the tradeoffs are different. I would probably be enthusiastic about changes which make it easier to read the document in more media. For example, in the past I've been motivated to fiddle with making the output preserve distinctions which are important in this document. For a particular example, when documenting CL it matters that ordinary word "list" is neither the <variable>list</> nor the function <function>list</> nor the type LIST, and "list" typed as user input is something else again. I suspect that that kind of thing could be done better than my hacks did it, and I'd be happy if it were. (It might also be that in the current style it's already done acceptably well by default, or that someone knowledgeable could point us to a similarly customized version done by someone else that we could be reusing, so that my SBCL-only hacks, motivated by limitations of some old style, are now obsolete.) I might also be enthusiastic about decorative changes which didn't interact strongly with the basics of presentation of information, but made the manual feel niftier or more entertaining or more comfortable. I quite like the flavor of Duane Bibby's illustrations in the old LaTeX manual, for example. For that matter I think the illustrations in the Martin book that I quote below are OK, too. However, tastes in what's nifty and entertaining and comforting can of course differ somewhat from person to person, so I'm not sure how decoration ideas would work out. -- William Harold Newman <wil...@ai...> We were bedevilled by the daemons of diagrammatic overdesign. My God, three little boxes drawn on the back of a napkin, Game, Frame, and Throw, and it was still too complicated and just plain wrong. -- Robert C. Martin, _Agile Software Development_, p. 72 PGP key fingerprint 85 CE 1C BA 79 8D 51 8C B9 25 FB EE E0 C3 E5 7C |
From: Miles E. <mi...@ca...> - 2003-11-07 21:09:27
|
On Fri, 2003-11-07 at 11:48, William Harold Newman wrote: > On Fri, Nov 07, 2003 at 08:52:14AM -0800, Miles Egan wrote: > > I've spent a little time trying to give the html docs a minimal css > > facelift to make them look a little less generic docbook. Please have = a > > look here: > >=20 > > http://www.caddr.com/sbcl-doc/ > >=20 > > If this is acceptable I can easily put it together as a small patch. >=20 > To me, "generic" is not necessarily a flaw in things, like > documentation, that people use for utility, as opposed to for > entertainment, or for fashion, or for other uses. To see someone > writing on a similar topic (with more confidence than I feel) try > http://tbray.org/ongoing/When/200x/2003/11/03/CuiBono > He's arguing that for active software systems a boring user interface > that's widely understood is a feature, not a bug. I feel that a > similar principle applies to the "user interface" of passive > documentation as well. For content aimed solely at developers I think I'd agree but for content that might be a potential new user's first exposure to the system this kind of documentation only reinforces their biases that lisp is old technology used only by a recalcitrant old guard. I agree with Bray that overly clever and decorative interfaces are usually more of a help than a hindrance, but something that preserves the original navigation and layout seems pretty harmless to me. Anyway, I can certainly see your point of view. The SBCL home page might be a more profitable target for this kind of work. How would you feel about some changes there? --=20 Miles Egan <mi...@ca...> |
From: Daniel B. <da...@te...> - 2003-11-07 22:17:51
|
William Harold Newman <wil...@ai...> writes: > marketing-related stuff in general. But my initial impression (using > the Mozilla 1.0.0 browser which came with my old Debian) is that the > new non-generic approach at > http://www.caddr.com/sbcl-doc/ > is not an improvement for the fundamental things documentation is > needed for. It does look different, of course, but I don't find it I'm replying to the thread: the quoted text is merely a not-quite random selection intended as an aide-memoire I had thoughts a few weeks ago about what I personally would like to see done to the documentation, which consisted less in markup and more in moveing large sections around and writing new ones. I haven't had time/inclination to implement any of this yet, but the outline is at http://sbcl-internals.cliki.net/The%20Manual and please gentlemen to give your gracious feedback -dan -- http://web.metacircles.com/cirCLe_CD - Free Software Lisp/Linux distro |
From: Miles E. <mi...@ca...> - 2003-11-07 22:24:38
|
On Fri, 2003-11-07 at 14:17, Daniel Barlow wrote: > I'm replying to the thread: the quoted text is merely a not-quite > random selection intended as an aide-memoire >=20 > I had thoughts a few weeks ago about what I personally would like to > see done to the documentation, which consisted less in markup and more > in moveing large sections around and writing new ones. I haven't had > time/inclination to implement any of this yet, but the outline is=20 > at http://sbcl-internals.cliki.net/The%20Manual and please gentlemen > to give your gracious feedback I like it. I'd be happy to help with any of it. --=20 Miles Egan <mi...@ca...> |
From: Neil S. <na...@ar...> - 2003-11-07 22:55:20
|
On Fri, Nov 07, 2003 at 10:17:36PM +0000, Daniel Barlow wrote: > I had thoughts a few weeks ago about what I personally would like to > see done to the documentation, which consisted less in markup and more > in moveing large sections around and writing new ones. As someone fairly new to Common Lisp, I'm looking forward to the sections on using contrib modules, how to avoid going insane, and delivering applications. I have lots of good documentation on Common Lisp the language but not so much on using SBCL for day-to-day development. Neil |
From: William H. N. <wil...@ai...> - 2003-11-08 01:11:30
|
On Fri, Nov 07, 2003 at 01:09:21PM -0800, Miles Egan wrote: > On Fri, 2003-11-07 at 11:48, William Harold Newman wrote: > > On Fri, Nov 07, 2003 at 08:52:14AM -0800, Miles Egan wrote: > > > I've spent a little time trying to give the html docs a minimal css > > > facelift to make them look a little less generic docbook. Please have a > > > look here: > > > > > > http://www.caddr.com/sbcl-doc/ > > > > > > If this is acceptable I can easily put it together as a small patch. > > > > To me, "generic" is not necessarily a flaw in things, like > > documentation, that people use for utility, as opposed to for > > entertainment, or for fashion, or for other uses. To see someone > > writing on a similar topic (with more confidence than I feel) try > > http://tbray.org/ongoing/When/200x/2003/11/03/CuiBono > > He's arguing that for active software systems a boring user interface > > that's widely understood is a feature, not a bug. I feel that a > > similar principle applies to the "user interface" of passive > > documentation as well. > > For content aimed solely at developers I think I'd agree but for content > that might be a potential new user's first exposure to the system this > kind of documentation only reinforces their biases that lisp is old > technology used only by a recalcitrant old guard. I agree with Bray > that overly clever and decorative interfaces are usually more of a help > than a hindrance, but something that preserves the original navigation > and layout seems pretty harmless to me. > > Anyway, I can certainly see your point of view. The SBCL home page > might be a more profitable target for this kind of work. How would you > feel about some changes there? Improving the home page would be a good idea, by definition.:-) My only reservation is like what I said about decorations in my original message, and like what I've said about patches on IRC and elsewhere: trying to work with people fixing outright bugs is easier than trying to work with people who want to remake a system to their tastes. As an example, people tend to agree whether a patch to Linux or Windows is a valid bug fix. It's not a perfect cooperative utopia, but most of the time diplomacy isn't really needed to straighten out disagreements. But people disagree strongly on whether Linux should be made more like Windows, and whether Windows should be made more like Linux. For that kind of issue, diplomacy is needed, and then all too often diplomacy turns out to be insufficient. And that kind of issue tends to arise all the time after "I've written code to add whizfeature to the system" or "please merge my patch to make the user interface more intuitive and flexible" or "let's make the website more attractive". So improving the website is good, yes. But realize that unless you can do such a fantastic job that everyone agrees control should simply be delegated to you, there'll probably be a fair amount of friction as you translate from the mission "improving the design of Linux^WWindows^Wthe website" to actual execution. People may disagree on things like what sorts of text is appropriately highlighted in red, whether conventional capitalization should be used, and so forth. Without any general technical consensus on what details should be, and without awed recognition that your overall design so clearly rocks the house down that mere mortals shouldn't quibble about details, there doesn't seem to be any natural limit to that kind of friction. I acknowledge your concern that SBCL may be made to appear to be old tech for recalcitrants, but then maybe I am a recalcitrant. I'm unlikely to be excited about anything graphically busier or more graphically innovative than http://gcc.gnu.org/, http://www.debian.org/, http://www.advogato.org/, http://norman.walsh.name/, or of course the famous http://www.google.com/. One could admittedly go some ways past http://sbcl.sourceforge.net/ before passing that threshold, but I'd prefer to err on the side of http://sbcl.sourceforge.net/ than e.g. http://www.linux.org/, http://www.perl.com/, http://www.redhat.com/, http://www.scripting.com/, http://www.travelocity.com/, http://www.amazon.com/, or for that matter http://sourceforge.net/projects/sbcl. Admittedly, there are some less austere websites that are widely liked. With that in mind, I realize it might be possible to do such a whizbang job that people, including me, will just be rocked back on their heels and shut the heck up. (If one of the better and more innovative CSS Zen Garden designers is out there reading this, longing to remake and maintain SBCL's website but heretofore too shy to volunteer, very likely something could be worked out.:-) But unfortunately I think it's enormously harder to make a site whizzy and cool and widely liked, and to keep it looking cool for more than 12 months, than to pessimize the plain vanilla default behavior. Incidentally, Dan's ideas for the manual seem much nearer the uncontroversial clearly-an-improvement-for-technical-reasons limit than most things which could be done to the website. (Although, now that I think of it, adding the manual to the website was also a pretty clear and uncontroversial improvement, so perhaps I shouldn't be so sure.) So I hope that work on the manual by Dan, by you, or by others -- possibly even me -- won't be subject to much design-by-committee contentious entropy. -- William Harold Newman <wil...@ai...> We were bedevilled by the daemons of diagrammatic overdesign. My God, three little boxes drawn on the back of a napkin, Game, Frame, and Throw, and it was still too complicated and just plain wrong. -- Robert C. Martin, _Agile Software Development_, p. 72 PGP key fingerprint 85 CE 1C BA 79 8D 51 8C B9 25 FB EE E0 C3 E5 7C |
From: Brian M. <bma...@cs...> - 2003-11-08 02:55:23
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Nov 7, 2003, at 11:52 AM, Miles Egan wrote: > I've spent a little time trying to give the html docs a minimal css > facelift to make them look a little less generic docbook. Please have > a > look here: > > http://www.caddr.com/sbcl-doc/ > > If this is acceptable I can easily put it together as a small patch. > > -- > Miles Egan <mi...@ca...> > Well, it's interesting, but I'm not sure I like how it looks all that much. For one, the links aren't underlined unless I hover over them, which is definitely NOT how my browser is set up. Why is this page overriding my browser? In addition, the spacing (eg only a newline and not a new paragraph between the "Table of Contents" header and the "Introduction" line) looks kind of weird. I will disclaim that I'm no fan of CSS pages though. My wishlist item would be to throw out docbook and DSSSSSSSSSSSSSSSL and replace it with something in CL that generated HTML 3.2 :-) - -- Brian Mastenbrook bma...@cs... http://cs.indiana.edu/~bmastenb/ -----BEGIN PGP SIGNATURE----- Version: PGP 8.0.3 iQA/AwUBP6xavGnXQDi0istxEQIiEACeN+u9U92BWL16924v8yzqNVb5MDMAn2e8 O8uy+2zQvoPZ9NtGQqqeVnm1 =qdO+ -----END PGP SIGNATURE----- |
From: Miles E. <mi...@ca...> - 2003-11-08 05:38:49
|
Thanks for the considered response. A few thoughts, all in my most H O: 1. As the most public visual face of a community, a project's web site should reflect the character and spirit of the community. So, if sbcl-devel does have a preference for a particular style or lack thereof that trumps any individual inclinations. 2. As the most public visual face of a community, a project's web site is also one of its most important marketing and recruiting tools. In many cases it will be the first impression a potential new user will make of the community. This is an important opportunity to portray the sbcl-community as a creative, active, vibrant and technically savvy group. The current design squanders that opportunity. 3. I don't consider myself an especially good designer, I just think there's an opportunity and a need here and nobody else seemed interested. 4. I didn't have anything as ambitious as CSS Zen Garden in mind. Ruby's home page (http://www.ruby-lang.org) is a better example of what I was thinking of. It does the following right: * simple, clean and lightweight design that renders well in most browsers * distinctive enough to present a clear personality and aesthetic without being too flashy or trendy * obviously actively maintained and updated and representative of ongoing work in the community Something like this would encourage a lot of curious people to take a closer look at SBCL. 5. A well-designed css style shouldn't interfere with the maintenance of content and should age very well. The version of the docs on caddr required no changes of any kind to the sgml documentation, for instance. Anyway, I understand your concerns and I agree that Dan's content and organization changes are a higher priority. I'd be happy to take on some of that too if it makes sense. miles |
From: Daniel B. <da...@te...> - 2003-11-08 15:00:50
|
Miles Egan <mi...@ca...> writes: > 4. I didn't have anything as ambitious as CSS Zen Garden in mind. > Ruby's home page (http://www.ruby-lang.org) is a better example of what > I was thinking of. It does the following right: > > * simple, clean and lightweight design that renders well in most > browsers > * distinctive enough to present a clear personality and aesthetic > without being too flashy or trendy > * obviously actively maintained and updated and representative of > ongoing work in the community Ghastly colours, though (at least on my screen). The news item title bars clash with the big block of colour at the head of the page. For first-time users it also suffers from the "you've been here before" problem that so many free project web sites seem to have: the front page of the site is full of minor news items that make no sense to the first-time reader, and they have to go off and hunt for an 'about' link. This is not to say that having news on the front page is bad, but it should at least be preceded by a couple of sentences saying "$FOO is the open source universe modeller, general problem solver, and MUA. Click _here_ for an overview" -dan -- http://web.metacircles.com/cirCLe_CD - Free Software Lisp/Linux distro |