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 19:50 UTC
> Google just announced Docsy, an open-source "documentation web site with > templates and guidance for documentation." We could mine it for ideas. > For example, it includes a nice theme based on Hugo. Here's an example > site created using it: > > https://example.docsy.dev/ Thanks for tipping us off about this. Unfortunately I have to advise against adopting any prefabricated theme or layout. From the blurb: > Have you ever struggled with the process of creating documentation for > an open source project? [...] great open source doc sites > aren't always easy to produce and share. Indeed it involves continual struggle. A great style in anything (food, dress, art, sports, speech) looks effortless but is quite hellish to produce. Originality has always come from struggle (not always struggle with the thing produced, but maybe with life itself, or with some other pursuit). A style is essentially a story of where one is in life and how one came there. That's why it can't be copied - if everyone tells the same story then no-one is telling anyone anything. And since people ultimately are not in the same place in life, copies look clumsy. (Unless there is no substance being copied in the first place, in which case both the original and the copies simply look lifeless). People who try to go by imitation are always punished by life sooner or later. The Bitbucket website was for a long time the most depressing looking site I visited. Eventually I sent them some feedback (almost a flame TBH) about how it feels like a cubicle farm (they used an incredibly lifeless combination of gray and blue) and they should change it to look elegant or playful instead. They didn't reply, but recently they've changed the colors several times to look gradually less corporate. Now they are using less depressing shades of gray, and there's some white where there was blue, etc. It's hilarious to watch how they realize they were wrong yet can't admit their mistake and redesign it outright. (I have no idea whether my feedback has anything to do with these changes, but the point stands regardless.) They could have changed it to something slightly playful like GitHub right away but they keep meandering around their original design, which was clearly borne out of insecurity (maybe they thought since they have some "enterprise" customers the site should look "professional" or whatever - I've no idea). But the result of that insecurity was that they built some copy of a copy that was completely devoid of human spirit. Sorry about the long-winded rant but this is important and will bite us if we go down the same path :) I can write more about this later, it takes quite a bit of energy to find the words.