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

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.