[gentoo-dev] Anyone interested in maintaining the Gentoo H..

On Sat, Oct 3, 2009 at 8:24 PM, AllenJB <gentoo-lists DeleteThis @allenjb.me.uk> wrote:
> The situation with the Gentoo Handbook is quite frankly getting beyond a
> joke for those of us donating our time to help users.
>
> I have tried to bring up the issues on the docs team list but pretty
> much get shot down and told everything is fine and dandy.
>
> For example, quoteth the Handbook at:
> http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=5
> Most PC users should use the stage3-i686-2008.0.tar.bz2 stage3 archive.
>
> This results in users starting out with a version of portage that
> doesn't understand EAPI-2. Guess what happens next.
>
> I personally would happily donate my time to working on the docs, if
> only it didn't involve a markup language nobody else uses.

You're in luck, the Beacon project has perfected it's Django branch
which is now nearly ready for deployment. I think this is a far better
option than converting all of the existing XML docs into Wiki and
alienating an entire team.

--
~Nirbheek Chauhan

GNOME+Mozilla Team, Gentoo

AllenJB wrote:
> Hi all,
>
> The situation with the Gentoo Handbook is quite frankly getting beyond a
> joke for those of us donating our time to help users.
>
> I have tried to bring up the issues on the docs team list but pretty
> much get shot down and told everything is fine and dandy.
>
> For example, quoteth the Handbook at:
> http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=5
> Most PC users should use the stage3-i686-2008.0.tar.bz2 stage3 archive.
>
> This results in users starting out with a version of portage that
> doesn't understand EAPI-2. Guess what happens next.
>
> I personally would happily donate my time to working on the docs, if
> only it didn't involve a markup language nobody else uses. I suggested a
> closed wiki for official documentation, but was again shot down saying
> that the existing team (who seem to be doing nothing) would need to
> reskill and that the server admins dislike wikis.
>
> Is it really satisfactory that the official install documentation
> results in a basically non-working install?
>
>
> AllenJB
>
>

I always use the x86 Quick install guide [1] I did an amd64 install
using it and can not recall changing anything. How about each arch
maintaining their own Quick install guide and for more in depth
questions point users to irc or the forums and put the handbook in the
archives for historical reference if no one wants to keep it current.

[1] http://www.gentoo.org/doc/en/gentoo-x86-quickinstall.xml


--
David Abbott (dabbott)
Gentoo PR
Gentoo trustee

Nirbheek Chauhan wrote:
> On Sat, Oct 3, 2009 at 8:24 PM, AllenJB <gentoo-lists.RemoveThis@allenjb.me.uk> wrote:
>> The situation with the Gentoo Handbook is quite frankly getting beyond a
>> joke for those of us donating our time to help users.
>>
>> I have tried to bring up the issues on the docs team list but pretty
>> much get shot down and told everything is fine and dandy.
>>
>> For example, quoteth the Handbook at:
>> http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=5
>> Most PC users should use the stage3-i686-2008.0.tar.bz2 stage3 archive.
>>
>> This results in users starting out with a version of portage that
>> doesn't understand EAPI-2. Guess what happens next.
>>
>> I personally would happily donate my time to working on the docs, if
>> only it didn't involve a markup language nobody else uses.
>
> You're in luck, the Beacon project has perfected it's Django branch
> which is now nearly ready for deployment. I think this is a far better
> option than converting all of the existing XML docs into Wiki and
> alienating an entire team.
>
What is the Beacon project? URL? A tried a quick bit of googling but
came up with nothing useful.

What entire team? Part of the problem is that there appears to be no one
working on the docs to start with. There's been a bug open on the 2008.0
-> autobuilds change open since February with, as far as I can tell,
nothing at all done towards fixing the handbooks. (
http://bugs.gentoo.org/260403 )

The last comment on that bug by a docs team member basically says:
> All the doc they need is 'Boot CD, follow on-screen instruction. If it fails,
> file a bug for the release team'. Done.
>
> Now, can we all forget abouth them?

Which I think is a very poor attitude for someone tasked with
maintaining the documentation (and appears to totally ignore the fact
that the abomination of an installer the GLI was has been long dead and
buried, even when that comment was made).

Just because you very rarely reinstall Gentoo, and once you've done it a
few times it's easy to do off-by-heart, that doesn't mean it should be
impossible for new users to ever install Gentoo for the first time. I
believe the Gentoo Handbook is a great, essential guide for new Gentoo
users - if only the install section actually worked!

AllenJB

Hi all,

I made a new install the other week-end and I found a couple of
strange things so I would like to help out. The only problem is that I
am pretty newb so I can only point out small things but i would like
to help. One big thing is that we now use eselect in a lot of cases.

In addition, I must say that we should have a couple of more sample
files, .config, xorg.conf and so on. If we would like to get some new
users, I think we should try to help them out a bit more. Just to get
started.

thanks,
Nik,

On Sat, Oct 3, 2009 at 4:54 PM, AllenJB <gentoo-lists RemoveThis @allenjb.me.uk> wrote:
> Hi all,
>
> The situation with the Gentoo Handbook is quite frankly getting beyond a
> joke for those of us donating our time to help users.
>
> I have tried to bring up the issues on the docs team list but pretty
> much get shot down and told everything is fine and dandy.
>
> For example, quoteth the Handbook at:
> http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=5
> Most PC users should use the stage3-i686-2008.0.tar.bz2 stage3 archive.
>
> This results in users starting out with a version of portage that
> doesn't understand EAPI-2. Guess what happens next.
>
> I personally would happily donate my time to working on the docs, if
> only it didn't involve a markup language nobody else uses. I suggested a
> closed wiki for official documentation, but was again shot down saying
> that the existing team (who seem to be doing nothing) would need to
> reskill and that the server admins dislike wikis.
>
> Is it really satisfactory that the official install documentation
> results in a basically non-working install?
>
>
> AllenJB
>
>

On Saturday 03 of October 2009 18:17:36 David Abbott wrote:
> I always use the x86 Quick install guide [1] I did an amd64 install
> using it and can not recall changing anything.

And i don't use any guide nor handbook any more, because i know what to do
step by step. That doesn't mean handbook should be dropped out for new users.

> How about each arch
> maintaining their own Quick install guide and for more in depth
> questions point users to irc or the forums and put the handbook in the
> archives for historical reference if no one wants to keep it current.

No. Wee only need to aply some patches to current handbook and everything
would be ok. The point is only doc team plus i believe few devs too have
write access to /doc/ section.

> [1] http://www.gentoo.org/doc/en/gentoo-x86-quickinstall.xml

AllenJB posted on Sat, 03 Oct 2009 18:03:16 +0100 as excerpted:

> http://bugs.gentoo.org/260403 )
>
> The last comment on that bug by a docs team member basically says:
>> All the doc they need is 'Boot CD, follow on-screen instruction. If it
>> fails, file a bug for the release team'. Done.
>>
>> Now, can we all forget abouth them?
>
> Which I think is a very poor attitude for someone tasked with
> maintaining the documentation (and appears to totally ignore the fact
> that the abomination of an installer the GLI was has been long dead and
> buried, even when that comment was made).

I checked the bug and it seems to me you're misinterpreting that
comment. The "they" he's referring to is the GLI. He says forget about
them -- "them" being the GLI. IOW, he knows that's old, and is saying
let's move on.

Of course, that doesn't help the docs point to something beyond the now-
broken 2008.0.

--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman

For what it's worth, I've got an updated PowerPC handbook pretty much
ready to go (still missing some sections that I want to add for the
PS3). However, I haven't gotten around to figuring out what all of the
XML replacement variables are currently and if they were going to change
to reflect autobuilds.

Whatever people decide to do, I'll port my work over to that.
-Joe

On Sat, Oct 3, 2009 at 10:33 PM, AllenJB <gentoo-lists.TakeThisOut@allenjb.me.uk> wrote:
> Nirbheek Chauhan wrote:
[...]
>>> I personally would happily donate my time to working on the docs, if
>>> only it didn't involve a markup language nobody else uses.
>>
>> You're in luck, the Beacon project has perfected it's Django branch
>> which is now nearly ready for deployment. I think this is a far better
>> option than converting all of the existing XML docs into Wiki and
>> alienating an entire team.
>>
> What is the Beacon project? URL? A tried a quick bit of googling but
> came up with nothing useful.

Hi,

I have just started setting up the above mentioned project's homepage.

Its available at: http://beaconeditor.org/

Mind you there is nothing much there, expect more in the coming week.
We have been hard at work to get this in shape for _quite_ sometime
(as many folks at Gentoo might have known). The development on this
project has been incremental, a few times a year. Though its picking
up momentum now.

For now you can see the Docbook Plugin (At the demo link) more or less
fully functional. GuideXML will be done in couple of days as well. The
aim to setup a project homepage is to give a much needed user feedback
and branded exposure to the project. There is a Trac setup there that
needs some sprucing up. Mailing lists inbound as well.

Hopefully with the rising needs of Gentoo and to make it possible to
stay with the existing setup (and not have to edit the XML) this
project can gain the traction.

FWIW, this project is at your disposal.

Kind Regards
Nandeep

Joshua Saddler wrote:
> On Sat, 03 Oct 2009 15:54:31 +0100
> AllenJB <gentoo-lists.RemoveThis@allenjb.me.uk> wrote:
>
>> I have tried to bring up the issues on the docs team list but pretty
>> much get shot down and told everything is fine and dandy.
>
> Going to have to call "bullshit" on this one. Who told you that on the lists? Have you *seen* *any* of the posts *I've* made? Take a look back at the list for the last, oh, year's worth of posts from me.
>
> We know there's stuff to do. There just aren't enough people. I do what I can, but I'm but one man.

As an example, quoteth one Joshua Saddler on 2009-07-19 on the -docs list:
I dunno if new blood is needed . . . we have perfectly capable folks in
the docs team. They've been around for a few (or more) years, and
they've invested the time and trouble to write perfect GuideXML. The
problem is getting them up *off* their asses to do the work.

>
>> I personally would happily donate my time to working on the docs, if
>> only it didn't involve a markup language nobody else uses. I suggested a
>> closed wiki for official documentation, but was again shot down saying
>> that the existing team (who seem to be doing nothing) would need to
>> reskill and that the server admins dislike wikis.
>
> "Who seem to be doing nothing."
>
> Thanks. Thanks for shitting all over my work for the last month/year/years. All the hours I spend each week (each day) even when I'm devaway maintaining docs in /doc/, /proj/, and our other www pages in /main/. Thanks for saying I do nothing.
>
> I know you're not aware of everything that's going on behind the scenes, but to make such a blanket statement is just uncalled for. I suggest you take a look at http://sources.gentoo.org/gentoo/xml/htdocs/ (doc/en/ and proj/en/) to see some commit history before making such an unkind statement.
>
> We're not totally dead. Not all of the team is inactive. I'm active. The translators are active. Our lead has been fielding the bugs as they come in.

I have no intention of "shitting all over" anybodys work. My apologies
if that was the interpretation. I'm simply escalating an issue I have
raised before to somewhere I think it'll get more attention.

Maybe you're not totally dead, but my criteria for activity has been the
multiple bugs I've been sitting on and the number of times I'm having to
tell new users "the handbook is wrong, ignore it and follow my
instructions in this case" or "oh dear! You seem to have installed a
version of Portage so ancient that 99% of our package tree can't be
installed" (or words to that effect) - mostly to do with the lack of
up-to-date handbooks, which as per my original post is now becoming a
dire situation, in my opinion.

>
> The problem with the English side of the docs is that I'm basically the only person doing anything. That means that while I can *sorta* keep up with the regular influx of non-handbook doc bugs, I can't do the entire handbook revamp on my own.*

>
> * Actually, I could, but some of the changes I have in mind are so far-reaching that I'd prefer not to go over the head of my team lead and instead stick to our existing policies rather than start breaking things left and right.

And you still want to claim you don't need new blood? For some odd
reason I seem to be hearing two different things from the same person.

If the rest of the team is dead, why not escalate the issue to, say the
-dev list. At least from what you've said in your most recent post you
seem to think _something_ does need to be done about the current situation.

AllenJB

Joshua Saddler wrote:
> On Sat, 3 Oct 2009 20:45:21 +0300 Markos Chandras
> <hwoarang.RemoveThis@gentoo.org> wrote:
>
>> This is actually true. Maybe all devs should have access on docs
>> since the docs teams are dead. I would suggest to let all
>> developers contribute to documentation whether they belong to docs
>> team or not
>
> No. Many (most?) devs do not write good documentation.
> <snip>
> They don't know all the myriad documents that need editing to
> pick up the change made to one part of a different document.
>

They say that the enemy of the great is the good, but I think that in
this case the enemy of the good is the great. Since many devs can't
write excellent documentation the argument is that they shouldn't be
permitted to write any documentation.

The problem with this is that some of our official documentation is just
outright wrong. Right now if somebody follows the docs they are
guaranteed to end up with a non-functional system. Suppose a dev edits
those docs and fixes the version but doesn't completely clean up the
accompanying text or misses some obscure cross-reference. Well, maybe
now a user has a 50% chance of getting it wrong - which is better than a
100% chance of getting it wrong. Others can then clean it up (such as
the folks on the forums who get all kinds of feedback about these sorts
of issues).

I'd be the first to agree that it would be better to just file a bug and
let the doc team clean up the docs. Perhaps this situation is just an
anomoly, in which case we shouldn't be changing overall policy as a
result. However, if we have a resource bottleneck here then we need to
do something to help clear it up. That isn't meant to reflect poorly on
anybody who is contributing to docs - you might be doing a wonderful job
but unless we can find more of you then you're going to be playing
whack-a-mole.

The amd64 team ran into a similar issue which is why there is a policy
that package maintainers are trusted to stabilize their own packages as
long as they've tested them on the platform. That doesn't mean that
there aren't decent amd64 team members - only that there simply aren't
enough of us to keep up with everything.