Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
Joshua Saddler wrote: On Sat, 3 Oct 2009 20:45:21 +0300 Markos Chandras 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. > 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.
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
On Sat, 3 Oct 2009 20:45:21 +0300 Markos Chandras 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. signature.asc Description: PGP signature
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
On Sun, 04 Oct 2009 00:58:56 +0100 AllenJB 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. signature.asc Description: PGP signature
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
Joshua Saddler wrote: > On Sat, 03 Oct 2009 15:54:31 +0100 > AllenJB 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
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
On Sat, 03 Oct 2009 15:54:31 +0100 AllenJB 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. signature.asc Description: PGP signature
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
On Sat, Oct 3, 2009 at 10:33 PM, AllenJB 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
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
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
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
> 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 signature.asc Description: This is a digitally signed message part.
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
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
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
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 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 > >
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
Nirbheek Chauhan wrote: > On Sat, Oct 3, 2009 at 8:24 PM, AllenJB 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
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
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
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
On Sat, Oct 3, 2009 at 8:24 PM, AllenJB 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
Re: [gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
On Sat, 03 Oct 2009 15:54:31 +0100 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? > 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
[gentoo-dev] Anyone interested in maintaining the Gentoo Handbooks?
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
