Gentoo Archives: gentoo-doc

From: Josh Saddler <nightmorph@g.o>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] Gentoo newbie ebook
Date: Wed, 31 Jan 2007 07:48:18
Message-Id: 45C049CA.2080604@gentoo.org
In Reply to: Re: [gentoo-doc] Gentoo newbie ebook by Ted Kosan
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

Attachments

File name MIME type
signature.asc application/pgp-signature

Replies

Subject Author
Re: [gentoo-doc] Gentoo newbie ebook Ted Kosan <tkosan@×××××.com>