Mailing List Archive

Hi Ted,
you might be interested in a draft of the "Introduction to Linux" stuff
[1] than one of our developers started some time ago. I'm not aware of
anyone working on it ATM, though.

Any contributions are more than welcome :)

[1] http://www.gentoo.org/doc/en/handbook/draft/complete/handbook.xml

Cheers,
-jkt

--
cd /local/pub && more beer > /dev/mouth
--
gentoo-doc@gentoo.org mailing list

Jan Kundrát wrote:
> Hi Ted,
> you might be interested in a draft of the "Introduction to Linux" stuff
> [1] than one of our developers started some time ago. I'm not aware of
> anyone working on it ATM, though.
>
> Any contributions are more than welcome :)
>
> [1] http://www.gentoo.org/doc/en/handbook/draft/complete/handbook.xml
>
> Cheers,
> -jkt

I've been occasionally contributing to it lately; I'm intending to
perhaps do some more with it. Really, a book on Linux in general would
be much more comprehensive. Problem is, a general book about Linux
fundamentals is not necessarily what Gentoo needs -- users (and
developers) need to know specifics about *our* OS. The general Linux
concepts they can pick up from just about anywhere. That information has
been duplicated ad infinitum; just stroll down to your local bookstore
or browse the web. You want to know the specific Gentoo stuff? Our
installation handbook and online documentation suffice quite nicely.

Newbies would do much better to familiarize themselves with general
Linux terms, principles, procedures etc. before taking the plunge into
Gentoo -- read outside documentation first; I'm not sure I see the need
to include that with our advanced guides. We're not a distro that holds
your hand. That being said, I think our documentation is rather
satisfactory -- I don't see the need for providing a new to Linux *and*
Gentoo book. Unnecessary duplication of information, including an
arguable waste of time and effort.

That's why I'm still up in the air about Sven's old draft handbook --
there's a very fine line to walk. You can either just write something
that is more generic, and has fewer distro-specific
commands/suggestions/discussions (in which case what's the point?) or
you can show users what they need to know to accomplish tasks "The
Gentoo Way". Finding the balance between the two (if there is one), is
tough. Especially since I'm not too sure that someone who first needs to
know how a computer works (or what it is!) should be trying to figure
out Gentoo just yet. ;) -- Hey, I could be wrong; maybe Gentoo would
make a great object lesson.

All that being said, do take a look at the draft Jan linked; it's
already CC-licensed, and our policy thus far (based on precedent) is
that we don't host documents here that haven't been guideXMLified and
properly licensed without the prior approval of the author(s).

Ted Kosan <tkosan@yahoo.com> posted
380006.98299.qm@web31811.mail.mud.yahoo.com, excerpted below, on Mon, 29
Jan 2007 21:55:30 -0800:

> I would like to explore the possibility of applying a creative commons (
> or similar ) license to the book and then make it available through the
> Gentoo website for use by Gentoo newbies and computer newbies in
> general. So far, the materials seem to be working well with high school
> senior age people and I also have a 13 year old and a 9 year old working
> through the book with few problems ( which is surprising :-)
>
> The Gentoo installation part of the book can be found here:
>
> http://tkosan.javadevices.org/distancelearning/etec150/lectures/gentoo_linux_install_phase_1_v1.3.1.pdf
>
>
> And here is the beginning part of the book, which contains an
> explanation of how a computer works:
>
> http://tkosan.javadevices.org/distancelearning/etec150/lectures/computer_systems.v1.0.pdf

Wow! I know someone whose kid is just getting into *ix and asked for
recommendations. This could be right up their alley as the kid is high
school age. Regardless of what Gentoo does with this, I know one person
that's getting a link to the class site (the etec150 dir) sent to them.
=8^)

(FWIW, he already decided to try FreeBSD first, so I don't know if this
will interest him or not, but given that it's setup as a distance learning
course and its limited previous knowledge target, it well could. FWIW2, I
just read thru both pdfs, then looked at the syllabus, quizzes, etc, and
not only am impressed, but learned a bit I had forgotten or somehow
skipped, going over the general computer basics in the first part myself.
=8^)

I'm impressed to see this use of Linux in the educational system happening
in the US, not just everywhere else, as it sometimes seems from the news.
When you are done developing the coursework, I'd love to see pieces on it
in LWN and/or sites such as Linuxwatch and linux.com/newsforge. I've got
the site bookmarked and may be mailing you offlist, as well.

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

--
gentoo-doc@gentoo.org mailing list

Jan wrote:

> you might be interested in a draft of the "Introduction to Linux" stuff
> [1] than one of our developers started some time ago.

Thank you for letting me know about this document. I had not seen it before
but I think it contains some very useful information.



Josh wrote:

> Problem is, a general book about Linux
> fundamentals is not necessarily what Gentoo needs -- users (and
> developers) need to know specifics about *our* OS. The general Linux
> concepts they can pick up from just about anywhere. That information has
> been duplicated ad infinitum; just stroll down to your local bookstore
> or browse the web. You want to know the specific Gentoo stuff? Our
> installation handbook and online documentation suffice quite nicely.

I think that a problem for most newbies is that they are overwhelmed by the
huge amount of Linux information that is available and they do not know where
to begin. Beyond this, most Linux-oriented information assumes the user has a
solid fundamental understanding of how a computer works. Many Linux experts
gained their understanding of how a computer works on relatively simple
machines ( like Commodore 64s and Apple IIs ) and when they began learning how
UNIX-like operating systems worked, the fundamental knowledge they already had
enabled them to grasp the UNIX information quickly.

Unfortunately, the fundamentals of how a computer works is not taught as widely
today as it was in the past and this lack of fundamental information is a huge
barrier that newbie must overcome before they start studying Linux.

I am not aware of any distros that are currently taking the time to provide
newbies with the fundamental pre-Linux computer knowledge they need. I do
think, however, that a distro that took on this challenge would generate a
significant amount of interest.



> That's why I'm still up in the air about Sven's old draft handbook --
> there's a very fine line to walk. You can either just write something
> that is more generic, and has fewer distro-specific
> commands/suggestions/discussions (in which case what's the point?) or
> you can show users what they need to know to accomplish tasks "The
> Gentoo Way". Finding the balance between the two (if there is one), is
> tough. Especially since I'm not too sure that someone who first needs to
> know how a computer works (or what it is!) should be trying to figure
> out Gentoo just yet. ;) -- Hey, I could be wrong; maybe Gentoo would
> make a great object lesson.

My opinion is that Gentoo does provide just the right technologies ( and just
the right balance between difficulty and simplicity ) to allow a newbie to go
from knowing almost nothing about computers through grasping the fundamentals.
Once they have the fundamentals, learning the Linux-oriented materials is much
easier.

It has been my experience that around 75% of the students who try to install
Gentoo Linux on their own, fail and give up. My expectation is that the
materials I have written should be able to drop the failure rate to below 25%.



> All that being said, do take a look at the draft Jan linked; it's
> already CC-licensed, and our policy thus far (based on precedent) is
> that we don't host documents here that haven't been guideXMLified and
> properly licensed without the prior approval of the author(s).

I like the draft document quite a bit, but the materials I have created are
aimed at a different goal than it is :-)

As for the document format, the materials I have written are currently in
OpenDocument format, but they could be transformed into another format like
guideXML. I think, however, that a case could be made for leaving them in a
format that has the look and feel of a traditional book.

Thanks,

Ted
tkosan@yahoo.com
--
gentoo-doc@gentoo.org mailing list

Duncan wrote:

> Wow! I know someone whose kid is just getting into *ix and asked for
> recommendations. This could be right up their alley as the kid is high
> school age. Regardless of what Gentoo does with this, I know one person
> that's getting a link to the class site (the etec150 dir) sent to them.
> =8^)

This is the kind of person I am trying to reach, every 13-20 year old in the
world that has an interest in computers but has no good way to start learning
about them. I have tried teaching beginners on some of the other distros (
including Redhat, Ubuntu and Linux From Scratch ) but they did not have the
balance between difficulty and simplicity that is needed by a beginner.

Another interesting thing here is that I think a significant number of Gentoo
users and developers know a kid or two who would like to learn the fundamentals
of computers and Linux :-)

Instead of just making the ebook available on the Gentoo site, my thought is
that a free online class based upon the book could periodically be offered by
the Gentoo foundation to anyone who is interested. I have had some experience
teaching free online software classes over the Internet to hundreds of students
at a time and this works quite well if done correctly.




> I'm impressed to see this use of Linux in the educational system happening
> in the US, not just everywhere else, as it sometimes seems from the news.
> When you are done developing the coursework, I'd love to see pieces on it
> in LWN and/or sites such as Linuxwatch and linux.com/newsforge. I've got
> the site bookmarked and may be mailing you offlist, as well.

My first choice would be to have pieces issued to the Linux news sites that
indicate that Gentoo is offering a free course to newbies based on these
materials. If Gentoo ends up not taking this route, I will probably pursue the
idea on my own, but I really think that Gentoo would not have much to lose by
at least trying this idea as an experiment :-)

Thanks,

Ted
tkosan@yahoo.com


--
gentoo-doc@gentoo.org mailing list

Ted Kosan wrote:
> As for the document format, the materials I have written are currently in
> OpenDocument format, but they could be transformed into another format like
> guideXML. I think, however, that a case could be made for leaving them in a
> format that has the look and feel of a traditional book.

As per our documentation policy[1], they must indeed be in guidexml.
Furthermore, I would argue that the web isn't too friendly a place for
the "booklike" format; PDFs and the ODF are not browser-friendly. For
all their much-touted cross-platform portability, they're not as easily
viewed as something universal like html, which is the rendered format of
our guidexml.

And, in my opinion, the guidexml handbook format for long documents
works much better than a booklike format; it's superior to vanilla
docbook as well -- another suggested format that comes up from time to time.

* * *

That being said, the question here is twofold: what would hosting your
work in progress do for Gentoo, and what would Gentoo hosting it do for it?

So far, I haven't come up with anything realistic for either. More
documentation or not, I still don't think adding something designed for
utter computer/Linux newbies would be of any help. One thing I heard
some other Gentoo devs mention the other day was that most of the
frustrations of new users (Gentoo users were the subject here, but I
think you can extrapolate this and apply it to Linux users in general)
are caused by a common mindset: they simply aren't accustomed to the
idea of reading in general. They *especially* aren't used to the idea
that they have to read technical documentation.

First they have to figure out what a livecd is -- but every single one
of them just expects things to "just work" out of the box like magic --
like Windows or OS X. Gentoo is not a distro in which things
automagically work or have been preinstalled for the user. That is where
our advanced documentation comes into place, and that's why I don't
think a newbies computer book will do anything for them, or for us, who
would have to maintain it. You're going to need some extremely
convincing arguments in favor of it before I, personally, will be sold
on the idea.

Regards,

Josh



[1] http://www.gentoo.org/proj/en/gdp/doc/doc-policy.xml

On Tue, 2007-01-30 at 21:56 -0800, Ted Kosan wrote:
> As for the document format, the materials I have written are currently in
> OpenDocument format, but they could be transformed into another format like
> guideXML. I think, however, that a case could be made for leaving them in a
> format that has the look and feel of a traditional book.

Keep in mind that we already have transformation scripts that we use for
the Handbook during releases to convert the GuideXML into PDF. One of
the advantages of GuideXML is the ability to transform it into other
things quite simply.

--
Chris Gianelloni
Release Engineering Strategic Lead
Alpha/AMD64/x86 Architecture Teams
Games Developer/Council Member/Foundation Trustee
Gentoo Foundation

Josh wrote:

> And, in my opinion, the guidexml handbook format for long documents
> works much better than a booklike format; it's superior to vanilla
> docbook as well -- another suggested format that comes up from time to time.


and Chris wrote:

>Keep in mind that we already have transformation scripts that we use for
>the Handbook during releases to convert the GuideXML into PDF. One of
>the advantages of GuideXML is the ability to transform it into other
>things quite simply.

As long as the format that the materials are placed into supports line numbers
and images/diagrams, I will be happy.



Josh wrote:

> That being said, the question here is twofold: what would hosting your
> work in progress do for Gentoo, and what would Gentoo hosting it do for it?
>
> So far, I haven't come up with anything realistic for either. More
> documentation or not, I still don't think adding something designed for
> utter computer/Linux newbies would be of any help. One thing I heard
> some other Gentoo devs mention the other day was that most of the
> frustrations of new users (Gentoo users were the subject here, but I
> think you can extrapolate this and apply it to Linux users in general)
> are caused by a common mindset: they simply aren't accustomed to the
> idea of reading in general. They *especially* aren't used to the idea
> that they have to read technical documentation.

I definitely agree that the problem of people not being accustomed to reading
is widespread.

However, after guiding numerous freshman classes through installing Gentoo
using the Gentoo Handbook, I have come to the conclusion that most of the
frustrations that these students experience are due to the Handbook not being
designed specifically for newbies ( and I think the Handbook is excellent at
what it is designed for, BTW ).

The reason I think this is because I am in the computer laboratory during the
installation process and I get to observe newbies working through the Handbook
step by step. I know everyone is reading the materials because I am constantly
running around the room, looking over everyone's shoulders and helping them
with their difficulties :-)

I have been teaching this class for about 3 years now and this has given me the
opportunity to see person after person encounter the same difficulties at the
same points in the Handbook. Over time, I found myself giving each student
that encountered a given difficulty a standard explanation which was helpful
for overcoming it. A significant portion of the gentoo_linux_install document I
have created consists of covering the same information that the beginning part
of the Handbook does, but at a much slower pace and with all of the difficult
parts I am currently aware of explained more fully.

Now, to address the questions in your first sentence. I am currently using the
materials in week 4 of a 10 week class and so they will be finished 6 weeks
from now ( unless I get hit by a truck or something :-) The size of the
overall document is at 135 pages now and I am projecting that the final
document will be between 175 and 200 pages. I am not proposing doing anything
with the materials until they are complete, other than having people here look
at them.



>What could the materials do for Gentoo?

- Cutting Gentoo's newbie frustration problem by perhaps 50%.

- Attracting a significant number of promising 13-20 year olds newbies to the
Gentoo site so that they can obtain fundamental computing knowledge which is
difficult to obtain elsewhere. If they are successfully able to finish the
materials, many of them will probably go on to become Gentoo users and perhaps
even developers.

- If the materials are used to periodically teach a free online class ( and I
will volunteer to teach it ), this would provide the opportunity to develop
news releases ( and perhaps articles ) which explain what the goal of the class
is, why it is unique and why Gentoo was the distro it was based upon. The
online class should provide different enough news content to attract the
interest of people who might not otherwise have considered looking at Gentoo.

I have more reasons I could list, but I think this is enough for now.



>What would Gentoo hosting it do for it?

My goal for the materials is to have them help as many frustrated computer
newbies as possible. I have taught free online classes in the past on more
specialized topics with class sizes up to 400. If marketed properly, Gentoo
classes based on these materials should have the potential to achieve class
sizes of 1000+. Having the materials eventually hosted by Gentoo would allow
them to benefit more easily from Gentoo's existing marketing capabilities.

Beyond this, Gentoo technologies are intimately woven into the fabric of these
materials and so I think they should be housed in a place where Gentoo
developers have easy access to them.



> You're going to need some extremely convincing arguments in favor of
> it before I, personally, will be sold
> on the idea.

Instead of trying too much harder to convince you, what I would like is the
opportunity to show you. What I have in mind is testing this idea by running a
small scale experimental newbie's class using the materials. I am not sure of
the best way to recruit newbies for the course, but perhaps locating people (
like Duncan's young friend ) through word of mouth would be sufficient.

Some members of the Gentoo Documentation Project could then monitor the course
and determine whether it is worth pursuing further after it is completed.


Respectfully,

Ted
tkosan@yahoo.com


--
gentoo-doc@gentoo.org mailing list

If I may say something, without having contributed to the Gentoo
project or its documentation.

What you, Ted, are doing looks like a very useful project, if
difficult and a lot of work. It does seem people, even students,
expect their computers to be easy and straightforward to use, while
ironically, just going through the gentoo installation process would
show them how much is involved to get things to work.

In general, I think the web is big enough, a link here or there, and
people will find your very useful guide. In particular, I would say a
beginner is equally likely to find your guide if it was on the gentoo
website, or anywhere else.

If you have trouble finding hosting, I'm sure I'd be able to help out.

In section 7.2.1, you might as well point out other VM possibilities,
like qemu. I feel it's a very good idea to add photos like around page
35.

Stephan

On 1/31/07, Ted Kosan <tkosan@yahoo.com> wrote:
> Josh wrote:
>
> > And, in my opinion, the guidexml handbook format for long documents
> > works much better than a booklike format; it's superior to vanilla
> > docbook as well -- another suggested format that comes up from time to time.
>
>
> and Chris wrote:
>
> >Keep in mind that we already have transformation scripts that we use for
> >the Handbook during releases to convert the GuideXML into PDF. One of
> >the advantages of GuideXML is the ability to transform it into other
> >things quite simply.
>
> As long as the format that the materials are placed into supports line numbers
> and images/diagrams, I will be happy.
>
>
>
> Josh wrote:
>
> > That being said, the question here is twofold: what would hosting your
> > work in progress do for Gentoo, and what would Gentoo hosting it do for it?
> >
> > So far, I haven't come up with anything realistic for either. More
> > documentation or not, I still don't think adding something designed for
> > utter computer/Linux newbies would be of any help. One thing I heard
> > some other Gentoo devs mention the other day was that most of the
> > frustrations of new users (Gentoo users were the subject here, but I
> > think you can extrapolate this and apply it to Linux users in general)
> > are caused by a common mindset: they simply aren't accustomed to the
> > idea of reading in general. They *especially* aren't used to the idea
> > that they have to read technical documentation.
>
> I definitely agree that the problem of people not being accustomed to reading
> is widespread.
>
> However, after guiding numerous freshman classes through installing Gentoo
> using the Gentoo Handbook, I have come to the conclusion that most of the
> frustrations that these students experience are due to the Handbook not being
> designed specifically for newbies ( and I think the Handbook is excellent at
> what it is designed for, BTW ).
>
> The reason I think this is because I am in the computer laboratory during the
> installation process and I get to observe newbies working through the Handbook
> step by step. I know everyone is reading the materials because I am constantly
> running around the room, looking over everyone's shoulders and helping them
> with their difficulties :-)
>
> I have been teaching this class for about 3 years now and this has given me the
> opportunity to see person after person encounter the same difficulties at the
> same points in the Handbook. Over time, I found myself giving each student
> that encountered a given difficulty a standard explanation which was helpful
> for overcoming it. A significant portion of the gentoo_linux_install document I
> have created consists of covering the same information that the beginning part
> of the Handbook does, but at a much slower pace and with all of the difficult
> parts I am currently aware of explained more fully.
>
> Now, to address the questions in your first sentence. I am currently using the
> materials in week 4 of a 10 week class and so they will be finished 6 weeks
> from now ( unless I get hit by a truck or something :-) The size of the
> overall document is at 135 pages now and I am projecting that the final
> document will be between 175 and 200 pages. I am not proposing doing anything
> with the materials until they are complete, other than having people here look
> at them.
>
>
>
> >What could the materials do for Gentoo?
>
> - Cutting Gentoo's newbie frustration problem by perhaps 50%.
>
> - Attracting a significant number of promising 13-20 year olds newbies to the
> Gentoo site so that they can obtain fundamental computing knowledge which is
> difficult to obtain elsewhere. If they are successfully able to finish the
> materials, many of them will probably go on to become Gentoo users and perhaps
> even developers.
>
> - If the materials are used to periodically teach a free online class ( and I
> will volunteer to teach it ), this would provide the opportunity to develop
> news releases ( and perhaps articles ) which explain what the goal of the class
> is, why it is unique and why Gentoo was the distro it was based upon. The
> online class should provide different enough news content to attract the
> interest of people who might not otherwise have considered looking at Gentoo.
>
> I have more reasons I could list, but I think this is enough for now.
>
>
>
> >What would Gentoo hosting it do for it?
>
> My goal for the materials is to have them help as many frustrated computer
> newbies as possible. I have taught free online classes in the past on more
> specialized topics with class sizes up to 400. If marketed properly, Gentoo
> classes based on these materials should have the potential to achieve class
> sizes of 1000+. Having the materials eventually hosted by Gentoo would allow
> them to benefit more easily from Gentoo's existing marketing capabilities.
>
> Beyond this, Gentoo technologies are intimately woven into the fabric of these
> materials and so I think they should be housed in a place where Gentoo
> developers have easy access to them.
>
>
>
> > You're going to need some extremely convincing arguments in favor of
> > it before I, personally, will be sold
> > on the idea.
>
> Instead of trying too much harder to convince you, what I would like is the
> opportunity to show you. What I have in mind is testing this idea by running a
> small scale experimental newbie's class using the materials. I am not sure of
> the best way to recruit newbies for the course, but perhaps locating people (
> like Duncan's young friend ) through word of mouth would be sufficient.
>
> Some members of the Gentoo Documentation Project could then monitor the course
> and determine whether it is worth pursuing further after it is completed.
>
>
> Respectfully,
>
> Ted
> tkosan@yahoo.com
>
>
> --
> gentoo-doc@gentoo.org mailing list
>
>


--
Stephan Wehner
> http://stephan.sugarmotor.org
> http://stephansmap.org
> http://www.trafficlife.com
> http://www.buckmaster.ca
--
gentoo-doc@gentoo.org mailing list