Mailing List Archive

On Sat, 03 Oct 2009 15:54:31 +0100
AllenJB <gentoo-lists@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?
>

I have seen many users happy with the unofficial wiki idea, and they
have expressed a "official" wiki would be great, and I share the same
idea.

Víctor

On Sat, Oct 3, 2009 at 8:24 PM, AllenJB <gentoo-lists@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@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@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

> 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.
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
>
> > [1] http://www.gentoo.org/doc/en/gentoo-x86-quickinstall.xml
--
Markos Chandras (hwoarang)
Gentoo Linux Developer [KDE/Qt/Sunrise/Sound]
Web: http://hwoarang.silverarrow.org

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

On Sat, 03 Oct 2009 15:54:31 +0100
AllenJB <gentoo-lists@allenjb.me.uk> 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. 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.

While I don't think there's anything wrong with our official docs being where
they are now, I'd kill for a dev-wiki to document the thousands of things we
all need to know that aren't written down anywhere.

And I know the response to this is going to be "if there's something that
should be documented, file a bug and get it into the dev manual/handbook".
While the dev manual is a good general overview of Gentoo development, there
is still a lot of stuff that isn't appropriate to document there. Having a
spot for package-specific maintenance docs was brought up a couple years ago
and shot down. Any documentation someone writes that doesn't fit into any
particular project ends up in someone's dev-space, where it's hard to find
unless you know it's there, dependent on one person to keep current, and lost
if that person retires. I've wanted to do gcc-porting guides for the last
couple releases, but I have nowhere to put them and am too slow/lazy to
figure out GuideXML and put them in my dev-space, where no one would see
them. We also have any number of "best practices" in Gentoo that generally
can only be discovered by breaking them and getting people annoyed with you;
things such as when it's okay to filter flags, how to use RESTRICT to handle
upstream changing a distfile without a name change, or when it's better to
not use a USE flag and just force an option. These things might be
appropriate for the dev manual but would benefit much more from the kind of
collaboration you get with a wiki environment. Development is a dynamic
thing and requires dynamic documentation.


--
fonts, Character is what you are in the dark.
gcc-porting,
wxwidgets @ gentoo EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662

On Sat, 03 Oct 2009 15:54:31 +0100
AllenJB <gentoo-lists@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.

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

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.

Joshua Saddler wrote:
> On Sat, 03 Oct 2009 15:54:31 +0100
> AllenJB <gentoo-lists@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

On Sun, 04 Oct 2009 00:58:56 +0100
AllenJB <gentoo-lists@allenjb.me.uk> wrote:
> 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.

I realize (now) it wasn't your intention. But that was how I took it. Just sayin'.

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

It is pretty bad -- it's news to me that EAPI2 is causing installation issues. That's on top of the interesting outdated packages and blockers seen when updating from something as old as 2008.

Problem is that there is no real "quick fix" for the handbooks, and there never was, even when the autobuilds were first introduced. It's not just a matter of changing version numbers. It's also the supporting text. It's also the variable infrastructure in our other handbooks that build the displayed text using a number of conditionals. Every file we have needs to be overhauled to match what should be a simple version change, because the autobuilds are very different.

Give me two or three straight days that I devote 12 hours of work to the docs per day, and three GDP members who can work some or all of that time, and I can get the handbooks done in a weekend. It's doable, it just needs a large block of time, and more people besides me doing all the work.

I've been doing solo handbook overhauls for the last several releases. It's not fun anymore. This is even more wide-reaching than that, since it involves core handbook design decisions that (I think) *require* getting my fellow team members and lead to review and consider.

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

This is an idea, but I don't know that it would accomplish much. I've chimed in on major package changes on the -dev list with a request for developers to talk with the GDP regarding related doc updates, but most of those kinds of requests go unanswered, or are answered very slowly.

Usually I jump on IRC as it's more likely that I'll enlist help from my fellow developers there, in real time: two very recent examples are the Xfce and X11 teams helping me out with my questions regarding the guides for 'em, and some stuff on bugzilla.

Something does need to be done about the number of active docs developers, and the number of non-GDP members contributing patches that I just need to commit with minimal review, thus acting as a commit proxy. But I can't *force* people to help out with the documentation -- that includes users and developers. Nor can I force our developers to have free time right when *I* need some answers WRT a doc.

On Sat, 3 Oct 2009 20:45:21 +0300
Markos Chandras <hwoarang@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. Their native language may not be English. They don't know the coding style. They don't know how to write code that validates. They're not good at putting together step-by-step instructions with helpful, explanatory text. They don't know all the myriad documents that need editing to pick up the change made to one part of a different document.

The GDP team is not dead, fer cryin' out loud. I just replied to Allen's message elsewhere in this same thread.

As I said in that thread, you can't force people to write documentation, patches, or even a plain-text list of "change foo to bar" alterations.

We still can't force developers to use repoman when they commit, or force developers to not break dependencies EVERY TIME they commit even with repoman. We can't force developers to contribute EVERY TIME they make a change to a package, or pick up upstream's changes. It'd be nice if we had a really integrated system for doing packages and docs at the same time, but it's not possible to make people do what you want them to do.

Joshua Saddler wrote:
> On Sat, 3 Oct 2009 20:45:21 +0300 Markos Chandras
> <hwoarang@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.