Re: Fwd: Google Open Source Blog: Announcing Docsy: A Website Theme for Technical Documentation Lassi Kortela (10 Jul 2019 20:29 UTC)

Re: Fwd: Google Open Source Blog: Announcing Docsy: A Website Theme for Technical Documentation Lassi Kortela 10 Jul 2019 20:29 UTC

>     I didn't mean that we should adopt it wholesale.  After all, we're
>     not using Hugo, upon which it is based.  I just wanted to share it
>     because it has some nice ideas about layout, site design,
>     typography, etc.

I know this is a subtle point and I apologize for not making an effort
to clarify it. When you just look for some ideas or inspiration from a
pre-made layout, it seems innocuous enough, but when you browse the
results (e.g. language sites, and many other kinds of sites) it's clear
that the overall flavor carries over even when people intended to copy
just some handy features.

This sounds almost offensively vague and airy, but a style kind of needs
to grow from a seed. It doesn't work so well to transplant different
things after the fact from outside places. You kind of have to take the
original style and nudge it in the direction you want. Sometimes it goes
there naturally, sometimes it doesn't work out, and we can't really tell
beforehand. I regret that I can't explain this properly either and I
feel quite embarrassed about using this kind of vocabulary.

>   It's very hard to get those things right, and
>   having some inspiration and sources for ideas can be helpful.

These are extremely true - it really is hard, and inspiration is
definitely necessary!

My point (which I again apologize for not making clearly) is that we
should look to inspiration in places other than programming and business
circles. I claim (again without explaining properly) that we'd get
better results by looking at photos of cafes or bridges than by looking
at programming sites. This may sound preposterous but I believe in it.

> I second that. Having idea is good. All racket documentation has the
> same look'n'feel that doens't make it a lack of personality but rather a
> pleasing experience.

I agree that <> looks good. But that's because it
looks different from doc browsers for other languages, and was clearly
designed by people with some good taste and vision. (The layout and
fonts slightly evoke the feel of a reading a paper book, without the
clumsiness aspects a paper book. The effect is subtle enough that it's
almost certain the designer deliberately wanted to do that.)

It's true that _within_ different manuals look the
same, but 1) it doesn't matter so much because the whole Racket site
still looks unique compared to all other language sites; and 2) even the
Racket site would look even better than it does now if each book looked
slightly different (this is a lot of effort, which is probably why they
didn't do it, but it would be a further improvement).

For Scheme sites, it might make sense for each implementation to have
its own background color for its pages, which is slightly different from
other implementations' colors. I'm not sure this would work but I'd like
to try it.

None of this fancy stuff is necessary, but what (I think) is necessary
is to avoid copying from others. I'm quite confident that better to have
a unique site that looks clumsy, than a slick site that looks like a
copy. And the clumsy site can always be polished later, but it's very
difficult to turn a copy into something original later.