Mailing List Archive

AllenJB wrote:
> Hi all,
>
> Is there a breakdown of tasks for updating the handbooks for autobuilds?
> I looked at bug #260403 but it doesn't seem to say what actually needs
> to be done (I also browsed through the other open docs bugs and there's
> barely anything related to the user handbook there).

This is something that I've brought up on this list all the way back at
the beginning of March[1]. Someone else raised the issue earlier this
month[2].

As of right now, no one's bothered to reply on the list, nor respond
when I jump on to our IRC channel.

For the record, I have updated /main/en/where.xml for bug 266464[3].

But as I'm the only one doing any work these days, I have no idea when
the rest might be completed. As far as I know I'm the only one to even
start to consider all the things that need to be changed.

A few off the top of my head:

1. Keys in handbook-$arch.xml files
- No longer need paths to point releases. Update paths to install media
on the mirrors.
- Kernel versions will change fairly rapidly with the autobuilds, even
though the stages only have stable kernels.
- Keep monitoring ISO/stage size, or else discard keeping this
information, which is already present in /main/en/where.xml. I'm in
favor of just using a range of MB, rather than a specific size. Means
less constant updating.
- Recommended CFLAGS, especially now that GCC 4.3 is stable. Includes
new arches for e.g. C2D, new arches that superset things. Better yet,
what about just using -march=native? Native detects what you have and
sets based on that.

2. Various renames that have happened now that we no longer do point
releases.

3. Handbook restructuring proposal. I've sent some variants to the list
a few times now, what with the lack of point releases for networked and
networkless media. Needs some rethinking, and though I could just
unilaterally *do something* (again, no one else is doing work), I need
the rest of the team involved. Plus our leader should sign off on any
big changes.
- Maybe just provide some kind of current-networked and
current-networkless link/symlink/directory? Similar to what the
autobuilds have. There's no longer a need to track a specific
networkless revision, not even as an archive, as the old files are not
preserved past a certain point.
- Some arches have build trouble at the moment, and do not provide
updated CDs (yet). This may require mixing and matching directions and
install media.
- More arches are adding autobuilds, including ARM, alpha, hppa. Must
update as these become available.

4. ???

5. Profit.

That's it for now, I guess.

[1]
http://archives.gentoo.org/gentoo-doc/msg_4db815c5379134f5047b268361977b3d.xml
[2]
http://archives.gentoo.org/gentoo-doc/msg_498f230e6f69df9091b8b2b1d39ce0fb.xml
[3] http://bugs.gentoo.org/266464

Josh Saddler wrote:
> AllenJB wrote:
>> Is there a breakdown of tasks for updating the handbooks for autobuilds?
>
> This is something that I've brought up on this list all the way back at
> the beginning of March[1].
>
> As of right now, no one's bothered to reply on the list, nor respond
> when I jump on to our IRC channel.
>
> But as I'm the only one doing any work these days, I have no idea when
> the rest might be completed. As far as I know I'm the only one to even
> start to consider all the things that need to be changed.
>
> [several points...] That's it for now, I guess.

To me this sounds like an issue that needs to be brought to the
attention of the council. Having good documentation has always been one
of the strengths of Gentoo. It would be sad to see that wither away
because of lack of manpower or lack of interest. Maybe we need to do
some targeted recruiting for the documentation team.

Cheers,
--
Ben de Groot
Gentoo Linux developer (qt, media, lxde, desktop-misc)
Gentoo Linux Release Engineering PR liaison
______________________________________________________

Ben de Groot wrote:
> Josh Saddler wrote:
>
>> AllenJB wrote:
>>
>>> Is there a breakdown of tasks for updating the handbooks for autobuilds?
>>>
>> This is something that I've brought up on this list all the way back at
>> the beginning of March[1].
>>
>> As of right now, no one's bothered to reply on the list, nor respond
>> when I jump on to our IRC channel.
>>
>> But as I'm the only one doing any work these days, I have no idea when
>> the rest might be completed. As far as I know I'm the only one to even
>> start to consider all the things that need to be changed.
>>
>> [several points...] That's it for now, I guess.
>>
>
> To me this sounds like an issue that needs to be brought to the
> attention of the council. Having good documentation has always been one
> of the strengths of Gentoo. It would be sad to see that wither away
> because of lack of manpower or lack of interest. Maybe we need to do
> some targeted recruiting for the documentation team.
>
> Cheers,
>
I have contributed a document to the documentation team. While it is
unrelated to the autobuilds and the handbook, it shows interest in the
team. I know that Josh has been doing an immense amount of work for the
doc team, which is evidenced by his name showing up as "editor" on tons
of the existing documents. As Ben said, documentation is one of the
strongest points of Gentoo, so we cannot let it go by the wayside. I'm
willing to learn the ins and outs of editing existing documents, and the
other aspects of the doc team.

Two people actively working on documents is not enough either, but it
will hopefully offset some of the labour. I don't think that the team
would have any trouble finding volunteers to help out with editing, and
that an announcement should be made on the forum.

--Zach

Nathan Zachary wrote:
> Ben de Groot wrote:
>> To me this sounds like an issue that needs to be brought to the
>> attention of the council. Having good documentation has always been one
>> of the strengths of Gentoo. It would be sad to see that wither away
>> because of lack of manpower or lack of interest. Maybe we need to do
>> some targeted recruiting for the documentation team.

Eh, the council is a governing body for technical issues. They're all
about setting policy for things like Portage and ebuilds. I'm not sure
that they need to be bothered by what's going on in the GDP.

> I have contributed a document to the documentation team.

* Which, by the way, I'm examining today. :)

> Two people actively working on documents is not enough either, but it
> will hopefully offset some of the labour. I don't think that the team
> would have any trouble finding volunteers to help out with editing, and
> that an announcement should be made on the forum.

Editing, or continual maintainance, is generally not a problem, assuming
that any bugs filed aren't for obscure subjects of which no one has any
knowledge. With the exception of big projects like updating all our docs
for OpenRC/Baselayout-2, the handbooks for autobuilds, or the Xorg guide
for xserver 1.5, even one person (me) can generally keep up with
day-to-day maintenance.

Where we really need help is in writing and maintaining *new*
documentation. Nate's Openbox draft is just the sort of thing that we need.

Now, on the forums and on our highly visible public mailing lists, I've
continually asked for help for years, wanting to get in some fresh new
talents to keep up with the English documentation. Unfortunately, since
I started helping write docs in 2005, we haven't seen a single new
dedicated English editor. Not someone who later becomes a developer, nor
a regular user from the Gentoo community.

Where we are more successful is in attracting new recruits for
translation teams. Our Internationalization subproject gets all the new
people. :)

I don't know that *advertising* is the problem . . . the problem is that
people just don't want to do the work. The most help we get is bug
reports (to varying degrees of helpfulness where they include
solutions), or occasional one-off new documents or substantial additions
to an existing guide.

I don't really blame folks for not wanting to do it, either -- there is
a lot of work to do. And it's not always something that can be satisfied
with a 30-second fix. Sure, in one weekend I may knock down our load of
bugs from 50 to 34, but in a couple of months it'll be back up to 50 or 60.

It takes a fair amount of dedicated time and effort to learn how
GuideXML and our coding style work. We have several tools and resources
available to help prospective recruits, but first someone has to show
willingness to learn. Not just willingness to learn, but the drive and
determination to improve our documentation by actually coming back and
contributing. :)

It's so extremely rare that it makes me think other distributions must
have the same manpower issues we do: it's just a universal "given" that
people don't want to write.

I'll start updating the PowerPC handbooks since it looks like we've got
the auto build working now. I'd still like to switch our handbook to the
combined ppc64/ppc32 handbook that I wrote around the time we did the
last release. I think the only thing holding that back before was the
different names for the ISOs and I don't think that's still a problem.

Thanks!
-Joe

Joseph Jezak wrote:
> I'll start updating the PowerPC handbooks since it looks like we've got
> the auto build working now. I'd still like to switch our handbook to the
> combined ppc64/ppc32 handbook that I wrote around the time we did the
> last release. I think the only thing holding that back before was the
> different names for the ISOs and I don't think that's still a problem.

Thanks, Joe!

Josh Saddler wrote:
> Nathan Zachary wrote:
>
>> Ben de Groot wrote:
>>
>>> To me this sounds like an issue that needs to be brought to the
>>> attention of the council. Having good documentation has always been one
>>> of the strengths of Gentoo. It would be sad to see that wither away
>>> because of lack of manpower or lack of interest. Maybe we need to do
>>> some targeted recruiting for the documentation team.
>>>
>
> Eh, the council is a governing body for technical issues. They're all
> about setting policy for things like Portage and ebuilds. I'm not sure
> that they need to be bothered by what's going on in the GDP.
>
>
>> I have contributed a document to the documentation team.
>>
>
> * Which, by the way, I'm examining today. :)
>
>
>> Two people actively working on documents is not enough either, but it
>> will hopefully offset some of the labour. I don't think that the team
>> would have any trouble finding volunteers to help out with editing, and
>> that an announcement should be made on the forum.
>>
>
> Editing, or continual maintainance, is generally not a problem, assuming
> that any bugs filed aren't for obscure subjects of which no one has any
> knowledge. With the exception of big projects like updating all our docs
> for OpenRC/Baselayout-2, the handbooks for autobuilds, or the Xorg guide
> for xserver 1.5, even one person (me) can generally keep up with
> day-to-day maintenance.
>
> Where we really need help is in writing and maintaining *new*
> documentation. Nate's Openbox draft is just the sort of thing that we need.
>
> Now, on the forums and on our highly visible public mailing lists, I've
> continually asked for help for years, wanting to get in some fresh new
> talents to keep up with the English documentation. Unfortunately, since
> I started helping write docs in 2005, we haven't seen a single new
> dedicated English editor. Not someone who later becomes a developer, nor
> a regular user from the Gentoo community.
>
> Where we are more successful is in attracting new recruits for
> translation teams. Our Internationalization subproject gets all the new
> people. :)
>
> I don't know that *advertising* is the problem . . . the problem is that
> people just don't want to do the work. The most help we get is bug
> reports (to varying degrees of helpfulness where they include
> solutions), or occasional one-off new documents or substantial additions
> to an existing guide.
>
> I don't really blame folks for not wanting to do it, either -- there is
> a lot of work to do. And it's not always something that can be satisfied
> with a 30-second fix. Sure, in one weekend I may knock down our load of
> bugs from 50 to 34, but in a couple of months it'll be back up to 50 or 60.
>
> It takes a fair amount of dedicated time and effort to learn how
> GuideXML and our coding style work. We have several tools and resources
> available to help prospective recruits, but first someone has to show
> willingness to learn. Not just willingness to learn, but the drive and
> determination to improve our documentation by actually coming back and
> contributing. :)
>
> It's so extremely rare that it makes me think other distributions must
> have the same manpower issues we do: it's just a universal "given" that
> people don't want to write.
>
>
I'm also thinking about doing some documentation on LXDE, and PekWM as
well. If there is anything in particular that needs documentation, I'd
be happy to look into the issues, even if I don't have previous
knowledge or experience. I have several test machines on which I can
try new configurations. :)

--Zach

Nathan Zachary wrote:
> I'm also thinking about doing some documentation on LXDE, and PekWM as
> well. If there is anything in particular that needs documentation, I'd
> be happy to look into the issues, even if I don't have previous
> knowledge or experience. I have several test machines on which I can
> try new configurations. :)

New DE stuff is always good, but right now the stuff that needs
documentation is what's in our bugzilla. :)

In particular, there are some CUPS and printing-related bugs that no
one's touched because none of us has the expertise on the subject.

Josh Saddler wrote:
> Nathan Zachary wrote:
> > I'm also thinking about doing some documentation on LXDE, and PekWM as
>
>> well. If there is anything in particular that needs documentation, I'd
>> be happy to look into the issues, even if I don't have previous
>> knowledge or experience. I have several test machines on which I can
>> try new configurations. :)
>>
>
> New DE stuff is always good, but right now the stuff that needs
> documentation is what's in our bugzilla. :)
>
> In particular, there are some CUPS and printing-related bugs that no
> one's touched because none of us has the expertise on the subject.
>
>
Okay, we can continue the conversation via email instead of on the
mailing list if you would like. I would be more than happy to try and
look at some of the bugs.

--Zach

Nathan Zachary wrote:

> Okay, we can continue the conversation via email instead of on the
> mailing list if you would like. I would be more than happy to try and
> look at some of the bugs.


Well, I joined the this list to help out with documentation. One of
the things I'm working on is installing older hardware with CF-to-ide
converters. What I need is a basic understanding of how a installation
differs with autobuilds vs the the existing handbook.



My suggestions is that once I get that knowledge assimilation of the
basics of using autobuild to perform an installation, to just
edit a copy of the handbook the way I think it should be modified. Put
the doc somewhere for others to review. Then maybe some 'master
editor' can look at my suggestions and others' suggestions and make a
final version. I like to use installation docs as I go through several
installations and refine the docs as I go. Slow but thorough and
inclusive. I lack experience in using autobuilds to do an
installation. So if somebody has some skeleton notes, I can use on
some on older machines, I can provide a modified doc, if that is
interesting to folks on the doc team? Perhaps it could be an
alternative installation guide that I maintain for Gentoo, because
on gentoo user, we always have folks that need help putting Gentoo
on older (586) hardware. I intend to be very verbose in adding
iptables for firewalls and Bind 9 for DNS primary and secondary
servers.


Otherwise, I'm open to suggestion as to how I can help. I've been
using Gentoo since 2004.1...... An I can can do the 586 firewalls
and DNS servers separate from this group...


James

Nathan Zachary wrote:
> I'm also thinking about doing some documentation on LXDE, and PekWM as
> well. If there is anything in particular that needs documentation, I'd
> be happy to look into the issues, even if I don't have previous
> knowledge or experience. I have several test machines on which I can
> try new configurations. :)

Documentation on LXDE would be very welcome. It's one of those things I
haven't really come around to yet. But the packages themselves need
maintenance too, and I just don't find the time to do everything I'd want.

Cheers,
--
Ben de Groot
Gentoo Linux developer (qt, media, lxde, desktop-misc)
Gentoo Linux Release Engineering PR liaison
______________________________________________________

Josh Saddler <nightmorph@gentoo.org> posted 49FA0A33.9010800@gentoo.org,
excerpted below, on Thu, 30 Apr 2009 13:29:39 -0700:

> Now, on the forums and on our highly visible public mailing lists, I've
> continually asked for help for years, wanting to get in some fresh new
> talents to keep up with the English documentation. Unfortunately, since
> I started helping write docs in 2005, we haven't seen a single new
> dedicated English editor. Not someone who later becomes a developer, nor
> a regular user from the Gentoo community.

Hmm... it takes some people years to be ready. Unfortunately, for them,
ready happens in its own time, and can't be rushed to any visible
effect. Fortunately, those same folks tend to stick around equally long,
and often see generations of others come and go.

So don't get too discouraged over it. OTOH, having some of those faster
evolving generations to help in the mean time helps with the load, and
unfortunately as you said, that hasn't happened here either.

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

please unsub me


--- Duncan <1i5t5.duncan@cox.net> schrieb am Fr, 1.5.2009:

> Von: Duncan <1i5t5.duncan@cox.net>
> Betreff: [gentoo-doc] Re: Handbooks / Autobuilds: What needs to be done?
> An: gentoo-doc@lists.gentoo.org
> Datum: Freitag, 1. Mai 2009, 13:30
> Josh Saddler <nightmorph@gentoo.org> posted
> 49FA0A33.9010800@gentoo.org,
> excerpted below, on Thu, 30 Apr 2009 13:29:39 -0700:
>
> > Now, on the forums and on our highly visible public
> mailing lists, I've
> > continually asked for help for years, wanting to get
> in some fresh new
> > talents to keep up with the English documentation.
> Unfortunately, since
> > I started helping write docs in 2005, we haven't
> seen a single new
> > dedicated English editor. Not someone who later
> becomes a developer, nor
> > a regular user from the Gentoo community.
>
> Hmm... it takes some people years to be ready.
> Unfortunately, for them,
> ready happens in its own time, and can't be rushed to
> any visible
> effect. Fortunately, those same folks tend to stick around
> equally long,
> and often see generations of others come and go.
>
> So don't get too discouraged over it. OTOH, having
> some of those faster
> evolving generations to help in the mean time helps with
> the load, and
> unfortunately as you said, that hasn't happened here
> either.
>
> --
> 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

>
> please unsub me
>
>
> --- Duncan <1i5t5.duncan@cox.net> schrieb am Fr, 1.5.2009:
> Von: Duncan <1i5t5.duncan@cox.net>
> Betreff: [gentoo-doc] Re: Handbooks / Autobuilds: What needs to be done?
> An: gentoo-doc@lists.gentoo.org
> Datum: Freitag, 1. Mai 2009, 13:30
> Josh Saddler <nightmorph@gentoo.org> posted
> 49FA0A33.9010800@gentoo.org,
> excerpted below, on Thu, 30 Apr 2009 13:29:39 -0700:
>
> Now, on the forums and on our highly visible public
> mailing lists, I've
>
> continually asked for help for years, wanting to get
> in some fresh new
>
> talents to keep up with the English documentation.
> Unfortunately, since
>
> I started helping write docs in 2005, we haven't
> seen a single new
>
> dedicated English editor. Not someone who later
> becomes a developer, nor
>
> a regular user from the Gentoo community.
> Hmm... it takes some people years to be ready.
> Unfortunately, for them,
> ready happens in its own time, and can't be rushed to
> any visible
> effect. Fortunately, those same folks tend to stick around
> equally long,
> and often see generations of others come and go.
>
> So don't get too discouraged over it. OTOH, having
> some of those faster
> evolving generations to help in the mean time helps with
> the load, and
> unfortunately as you said, that hasn't happened here
> either.
>
> --
> 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
>

KKH, send an empty email to gentoo-doc+unsubscribe@gentoo.org