Gentoo Logo
Gentoo Spaceship




Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-doc
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Headers:
To: gentoo-doc@g.o
From: Josh Saddler <nightmorph@g.o>
Subject: Re: Gentoo newbie ebook
Date: Tue, 30 Jan 2007 23:48:26 -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.

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

Attachment:
signature.asc (OpenPGP digital signature)
Replies:
Re: Gentoo newbie ebook
-- Ted Kosan
References:
Re: Gentoo newbie ebook
-- Ted Kosan
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
Re: Gentoo newbie ebook
Next by thread:
Re: Gentoo newbie ebook
Previous by date:
Re: Re: Gentoo newbie ebook
Next by date:
Re: Gentoo newbie ebook


Updated Jun 17, 2009

Summary: Archive of the gentoo-doc mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.