Re: [gentoo-doc] Re: okupy, a Django rewrite of www.g.o

[wireless]

On 06/02/11 08:15, Jan Kundrát wrote:
> On 06/02/11 13:54, Theo Chatzimichos wrote:
>> Hey man, relax! :)
>> I'm also a translator, I have some ideas/needs that need to implement.
>> I was going to ask you (you as in other translators) for additional
>> ideas, I just didn't get there yet, i'm still struggling with the LDAP
>> backend for the time being.

> Theo, I'm not sure how to articulate my point in a better way here. I
> would've thought that you would ask your target audience *before* you
> got your project approved.

> Anyway, I said what I wanted to say, so let's just use this opportunity
> to produce something useful. /me crosses fingers.

EVERYONE is missing the point, imho.

ANY documentation system *should* have a facility where anyone can
create content, quickly and not as part of the *glorified* official
documentation. Fast moving technologies, such as open-source software
would do much to *EXCITE* the user base, if documentations was easy,
a little sloppy on form and features, but *CURRENT* on key information.
In lieu of this sort of scenario, folks repeatedly handle support, via
a variety of means.

As the content gets refined and becomes quite reasonable (as usually
happens over time) *THEN* it can be put into proper form. The lack of
this sort of "quick and easy" approach leads to too many
details that make Gentoo Documentation, substandard (not current)
at best. At all if you ask most folks, the freshness of current content
far outweighs the importance of appearance, for documentation. Hundreds
of times I have sent private email to folks of sloppy content notes
on how I fixed something, and *EVERYTIME* they are most grateful for
the currentness of the information, despite it being just a sloppy
(VI) raw-text file. *PRETTY without CONCURRENCY* is mostly useless,
imho. Just look at the docs related to building a software raid
system for a new gentoo installation, for example. Pathetic!
Yet software raid is a fundamental need that needs to converted into
a "GENTOO COMMODITY", imho.


Over the last 7 years, I've watched hundreds of very smart and
reasonable folks come to gentoo, want to update or create good
documentation and work *WITH* the gentoo devs. Hard-line attitudes
cause them to leave, quickly, in many circumstances. Documentation,
is quite often the key issue.

Time and again the arcane gymnastics that are employed (to a point
of cult worship) take precedence on content enhancement. Until this
is fixed (technically and attitudinally) you'll never keep up on
documentation or attracting bright folks to contribute to docs.

So most technical folks that stay with Gentoo, just fade into the
background........

That is what needs fixing *OVERWHELMINGLY* compared to any of these
other trite issues and fiefdoms.......

If you really want this maze to create documents, then *FIRST* create
the docs that folks can follow to create acceptable docs. Keeping this
sort of *CLEAR* information from the masses is the equivalent of
Fiefdom, or at least that is the appearance that others perceive.
Me, I just make my own docs and do not worry about sharing them
because the overall attitude of the those that control Gentoo,
particular the DOC teams.....imho.

I'm very sorry if this sort of email hurts anyone's feelings, but,
you really should live where the average user lives for a few days
and LISTEN for a bit.  Gentoo is no longer a "sole proprietor system"
it is a multi-national conglomerate and documentation should be the
first training ground for those seeking the "DEV" status, imho.


apologetically,
James