| 1 |
Ted Kosan wrote: |
| 2 |
> As for the document format, the materials I have written are currently in |
| 3 |
> OpenDocument format, but they could be transformed into another format like |
| 4 |
> guideXML. I think, however, that a case could be made for leaving them in a |
| 5 |
> format that has the look and feel of a traditional book. |
| 6 |
|
| 7 |
As per our documentation policy[1], they must indeed be in guidexml. |
| 8 |
Furthermore, I would argue that the web isn't too friendly a place for |
| 9 |
the "booklike" format; PDFs and the ODF are not browser-friendly. For |
| 10 |
all their much-touted cross-platform portability, they're not as easily |
| 11 |
viewed as something universal like html, which is the rendered format of |
| 12 |
our guidexml. |
| 13 |
|
| 14 |
And, in my opinion, the guidexml handbook format for long documents |
| 15 |
works much better than a booklike format; it's superior to vanilla |
| 16 |
docbook as well -- another suggested format that comes up from time to time. |
| 17 |
|
| 18 |
* * * |
| 19 |
|
| 20 |
That being said, the question here is twofold: what would hosting your |
| 21 |
work in progress do for Gentoo, and what would Gentoo hosting it do for it? |
| 22 |
|
| 23 |
So far, I haven't come up with anything realistic for either. More |
| 24 |
documentation or not, I still don't think adding something designed for |
| 25 |
utter computer/Linux newbies would be of any help. One thing I heard |
| 26 |
some other Gentoo devs mention the other day was that most of the |
| 27 |
frustrations of new users (Gentoo users were the subject here, but I |
| 28 |
think you can extrapolate this and apply it to Linux users in general) |
| 29 |
are caused by a common mindset: they simply aren't accustomed to the |
| 30 |
idea of reading in general. They *especially* aren't used to the idea |
| 31 |
that they have to read technical documentation. |
| 32 |
|
| 33 |
First they have to figure out what a livecd is -- but every single one |
| 34 |
of them just expects things to "just work" out of the box like magic -- |
| 35 |
like Windows or OS X. Gentoo is not a distro in which things |
| 36 |
automagically work or have been preinstalled for the user. That is where |
| 37 |
our advanced documentation comes into place, and that's why I don't |
| 38 |
think a newbies computer book will do anything for them, or for us, who |
| 39 |
would have to maintain it. You're going to need some extremely |
| 40 |
convincing arguments in favor of it before I, personally, will be sold |
| 41 |
on the idea. |
| 42 |
|
| 43 |
Regards, |
| 44 |
|
| 45 |
Josh |
| 46 |
|
| 47 |
|
| 48 |
|
| 49 |
[1] http://www.gentoo.org/proj/en/gdp/doc/doc-policy.xml |
Archives