Mailing List Archive

On Thu, Jun 2, 2011 at 1:13 PM, Jan Kundrát <jkt@gentoo.org> wrote:
> Hi,

Hi, thanks for your mail. My answer will be short though :)

> First of all, a suggestion -- maybe, when you want to do something to
> the docs (like change the presentation layer, integrate a WYSIWYG
> editor, convert to git from CVS, or stuff like that -- which are all the
> objectives of the project [2]), maybe it would be a great idea to
> contact the GDP first. There are fine contacts for chatting with us,
> either the nice gentoo-doc ML, or the #gentoo-doc IRC channel, or the
> docs-team@g.o alias. I have no idea whether Theo contacted anyone
> directly, but I'm sure I haven't received anything through any of these
> channels. That's bad, and it means that there's a communication problem
> somewhere.

Sure, I contacted Josh who showed much interest to my idea, and Infra
to make sure they (we) are willing to replace gorg

> Theo also mentions that "By all appearances Gorg has been abandoned as a
> project. This has resulted in difficulty in maintaining the Gentoo
> website, and also makes the work of updating the website's design or
> functionality all the more troublesome." and goes on to mention that
> "Gorg as an abandoned project is suffering from bugs that get pilled up,
> not to mention possible security risks that may arise". Can I ask for a
> reference to the "bugs that get pilled up", and to Gorg resulting in
> "difficulty in maintaining the Gentoo website"?

Gorg currently has two very important bugs open in bugzilla. We've
faced a couple more recently. The reality is that Gorg's developer
retired and stopped working on it, and noone in infra is willing to
touch it as well. Plus, we don't like using outdated / ambandoned
projects, especially for security reasons.

> Please don't get me wrong, I certainly do not want to hinder any efforts
> targeted at making our website better, or our workflow faster for those
> that really contribute. I just tend to get slightly upset when I see an
> approved GSoC project which will, IMHO, fundamentally change the way how
> GDP works, then read a few assertions that fail to persuade me, and
> realize that I can't find any notice of what is going to happen until
> after the project got approved -- that's a sure way to piss me of.
>

Nothing will change for GDP. The GuideXML will continue to exist, you
will be able to edit XML files directly as usual. There will be only
improvements here (like stats for translators, an editor, etc).

> Anyway, I really hope I'm just a weird, grumpy guy who somehow missed a
> well-targeted discussion. Hence, please do correct my impressions.
>

If you need any other information from my part, I'll be happy to provide it.

> In the meanwhile, have fun
> Jan

On 06/02/11 12:29, Theo Chatzimichos wrote:
> Sure, I contacted Josh who showed much interest to my idea, and Infra
> to make sure they (we) are willing to replace gorg

Hi Theo, thanks for clarification and for your reply. Too bad Josh did
not pass the word along the GDP. Given how much stuff he does, I'm sure
he was just swamped with work.

> Gorg currently has two very important bugs open in bugzilla.

I went through the Bugzilla [1] before I sent that mail, hence this
question. Bug 336055 looks like an Apache problem (and is trivially
fixable), bug 342569 is a feature of how the Gentoo-specific XSLT
stylesheets work, and in no way Gorg-specific (and could be probably
RESO/INVALID immediately). Looks like the only real issue is bug 315487,
the compatibility with Ruby 1.9.

> We've faced a couple more recently.

Again, this is rather hard to evaluate without any evidence. I've been
running Gorg on a non-Gentoo web site for years, so I do agree that it
takes some effort to set up (like any other server application), but
without specific references to problems, it's hard to judge how much of
a troublemaker Gorg really is.

I do understand your desire not to use abandoned projects -- that's a
very reasonable stance.

> Nothing will change for GDP. The GuideXML will continue to exist, you
> will be able to edit XML files directly as usual. There will be only
> improvements here (like stats for translators, an editor, etc).

See, this is *exactly* why I wrote this mail. What are "statistics for
translators"? I'm a translator myself, and nobody asked me what could
help me. What translators indicated that they consider that an
improvement over current way with metadoc.xml/overview.xml/trads.rb?

I welcome the change to git, it's great that you're willing to undertake
it, but it will surely affect the way how GDP works.

Whether a WYSIWYG editor is an improvement (or would just cause troubles
for translators due to line noise in diffs) is debatable IMHO, but that
discussion has been already started and abandoned several times.

Cheers,
Jan

[1] http://bugs.gentoo.org/buglist.cgi?quicksearch=gorg&list_id=200467

--
Trojita, a fast e-mail client -- http://trojita.flaska.net/

On Thu, Jun 2, 2011 at 2:47 PM, Jan Kundrát <jkt@gentoo.org> wrote:
>> Nothing will change for GDP. The GuideXML will continue to exist, you
>> will be able to edit XML files directly as usual. There will be only
>> improvements here (like stats for translators, an editor, etc).
>
> See, this is *exactly* why I wrote this mail. What are "statistics for
> translators"? I'm a translator myself, and nobody asked me what could
> help me. What translators indicated that they consider that an
> improvement over current way with metadoc.xml/overview.xml/trads.rb?
>

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.

> I welcome the change to git, it's great that you're willing to undertake
> it, but it will surely affect the way how GDP works.
>
> Whether a WYSIWYG editor is an improvement (or would just cause troubles
> for translators due to line noise in diffs) is debatable IMHO, but that
> discussion has been already started and abandoned several times.
>
> Cheers,
> Jan
>
> [1] http://bugs.gentoo.org/buglist.cgi?quicksearch=gorg&list_id=200467
>
> --
> Trojita, a fast e-mail client -- http://trojita.flaska.net/
>
>

PS Sorry for the duplicate, I sent it only to you the first time by mistake

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.

Cheers,
Jan

--
Trojita, a fast e-mail client -- http://trojita.flaska.net/

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

torsdagen den 2 juni 2011 19:22:49 skrev wireless:
> apologetically,
> James

Oh how I love a good rant.

This is actually pretty close the my reasoning for contributing to the wiki.
First, it's a wiki. Second, it's not within Gentoo's governance. Third, it's a
wiki.

On 06/02/11 19:22, wireless wrote:
> If you really want this maze to create documents, then *FIRST* create
> the docs that folks can follow to create acceptable docs.

I fail to see how your suggestion to create more docs describing
documentation policies are supposed to actually help address the problem
you described at the beginning of your e-mail, the "lack of
documentation freshness". Or maybe my sarcasm meter is broken today.
Anyway, why don't you contribute to some Gentoo wiki?

Cheers,
Jan

--
Trojita, a fast e-mail client -- http://trojita.flaska.net/

On Thu, 02 Jun 2011 13:47:09 +0200
Jan Kundrát <jkt@gentoo.org> wrote:

> On 06/02/11 12:29, Theo Chatzimichos wrote:
> > Sure, I contacted Josh who showed much interest to my idea, and
> > Infra to make sure they (we) are willing to replace gorg
>
> Hi Theo, thanks for clarification and for your reply. Too bad Josh
> did not pass the word along the GDP. Given how much stuff he does,
> I'm sure he was just swamped with work.

Indeed. Actually, I thought I mentioned it a time or two, on one of
my infrequent visits to #gentoo-doc or the mailing lists, but it may
have slipped my mind entirely.

Basically, if it would ease contribution without disrupting the
experienced contributors' current GuideXML workflow, I'm all for it.
Maintaining all this stuff by myself sucks.

Okupy is an independent project, as many efforts to revamp and expand
our website/docs have been, so I don't see that it'll do any harm.
Okupy development doesn't seem like it would interfere with
maintaining our existing documentation. I would like a few other devs
be willing to answer questions from the Okupy crowd; I'm not on IRC
enough to provide realtime feedback.