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