Re: [Sbcl-devel] sprucing up the documentation

[Miles E. <mi...@ca...>]

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...>