Posted by: Administrator
on September 20, 2004 06:31 PM
I'd like to comment on the following statement which is targeted at me:
My chief complaint about it is that it badly needs a competent editor; the authors get too chatty and go into details that are best left for footnotes or a separate section or sidebar for special-case situations.
I'm sorry to hear that you find the Gentoo Handbook incompetently written. I encourage you to go visit the Gentoo Bugtracking website and search for all the bugs regarding the Gentoo Handbook that have been resolved so far. You'll notice that the current Gentoo Handbook is written with the users in mind and with all (well, most) user feedback integrated.
Writing documentation isn't easy, on the contrary. It is impossible to satisfy everybody. My GDP (Gentoo Documentation Project) fellow writers and I have the quite difficult job to write documentation that pleases most users.
Together with this comes the fact that the Gentoo Installation allows for great flexibility. Not all users want to be informed about this flexibility, but most are. That's why the Gentoo Handbook is written so verbose: users who want to learn can do this easily by reading the Gentoo Handbook. Those who don't can just follow the steps needed to install Gentoo and skip the less relevant parts.
Taking the history of the gentoo installation instructions in mind, they have evolved from a 3-page document into a 90+ pages booklet. This is not because the editors and I have so much time on our hands that we continuously add new sections to it, but because we take all user feedback into account from which we clearly hear the need for a complete installation document which covers each and every task of the installation.
I encourage you to report any issues you came across while reading the Gentoo Handbook. If I am too chatty at certain sections, please tell me where and I'll see if I can update the Gentoo Handbook if appropriate.
Learn about Linux
Download Linux
Get Linux help
Writing documentation
Posted by: Administrator on September 20, 2004 06:31 PMI'd like to comment on the following statement which is targeted at me:
I'm sorry to hear that you find the Gentoo Handbook incompetently written. I encourage you to go visit the Gentoo Bugtracking website and search for all the bugs regarding the Gentoo Handbook that have been resolved so far. You'll notice that the current Gentoo Handbook is written with the users in mind and with all (well, most) user feedback integrated.
Writing documentation isn't easy, on the contrary. It is impossible to satisfy everybody. My GDP (Gentoo Documentation Project) fellow writers and I have the quite difficult job to write documentation that pleases most users.
Together with this comes the fact that the Gentoo Installation allows for great flexibility. Not all users want to be informed about this flexibility, but most are. That's why the Gentoo Handbook is written so verbose: users who want to learn can do this easily by reading the Gentoo Handbook. Those who don't can just follow the steps needed to install Gentoo and skip the less relevant parts.
Taking the history of the gentoo installation instructions in mind, they have evolved from a 3-page document into a 90+ pages booklet. This is not because the editors and I have so much time on our hands that we continuously add new sections to it, but because we take all user feedback into account from which we clearly hear the need for a complete installation document which covers each and every task of the installation.
I encourage you to report any issues you came across while reading the Gentoo Handbook. If I am too chatty at certain sections, please tell me where and I'll see if I can update the Gentoo Handbook if appropriate.
With kind regards,
Sven Vermeulen
Gentoo Documentation Project Lead
#