Fwd: Google Open Source Blog: Announcing Docsy: A Website Theme for Technical Documentation
Arthur A. Gleckler
(10 Jul 2019 18:31 UTC)
|
Re: Fwd: Google Open Source Blog: Announcing Docsy: A Website Theme for Technical Documentation
Lassi Kortela
(10 Jul 2019 19:51 UTC)
|
Re: Fwd: Google Open Source Blog: Announcing Docsy: A Website Theme for Technical Documentation
Arthur A. Gleckler
(10 Jul 2019 19:55 UTC)
|
Re: Fwd: Google Open Source Blog: Announcing Docsy: A Website Theme for Technical Documentation
Amirouche Boubekki
(10 Jul 2019 20:01 UTC)
|
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 <docs.racket-lang.org> 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_ docs.racket-lang.org 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.