The Handbook is excellently written, but could benefit from better organization and guidance. a) Mark ALL steps that are optional clearly, for instance with different color font or background. That files that do not have to be edited, setting Place and Time, etc. After the optional section, indicated clearly what to do in order to continue, like for example IF SKIPPED: cd /mnt/gentoo/dev chroot /bin/bash mount --this /option /dev/sda1 /boot etc. so that users can pick up at the correct spot. b) Please indicate reasonable default option(s) or starting points every time a menu needs to be edited These are two suggestion in addition to the one I made in my previous bug. Reproducible: Always
Please discuss at the relevant handbook talk page, e.g.: https://wiki.gentoo.org/wiki/Handbook_Talk:AMD64/Full/Installation
(In reply to John Helmert III from comment #1) > Please discuss at the relevant handbook talk page, e.g.: > > https://wiki.gentoo.org/wiki/Handbook_Talk:AMD64/Full/Installation c) All the "educational" parts about disks, file formats, partitions, connecting to the internet, etc. should be marked clearly as "background material" and given a special color background. I have written extensive comments on the whole Handbook for the AMD64 version, but I do not know where to send it.
I think you should provide that input at the relevant handbook talk page.
(In reply to John Helmert III from comment #3) > I think you should provide that input at the relevant handbook talk page. Hi John, I have probably over 50 suggestions. I do not have the time to write them all into your discussion. But I can send them to someone. Also, if you need a discussion like that for every little revision, you will never arrive a neat little document. To edit a document implies getting rid of materials that are excellently written, displays deep knowledge, that someone is very proud of, etc. simply because it does not fit or complicates too much. That is not the process you have on the talk page. You must give this talk to an editor, if need be a professional editor. Then your members can focus the discussions on technical issues. I have tested the live ISO. It is simply wonderful. But as it is you are preventing the installation and use of Gentoo with an excellently written, technically very good, and extremely poorly edited and very disorganized Handbook. This is not a great state of affairs. Best, Tormod
(In reply to Tormod Lunde from comment #4) > (In reply to John Helmert III from comment #3) > > I think you should provide that input at the relevant handbook talk page. > > Hi John, I have probably over 50 suggestions. I do not have the time to > write them all into your discussion. But I can send them to someone. > If you don't have time to write them, how can anyone have time to implement them? > Also, if you need a discussion like that for every little revision, you will > never arrive a neat little document. To edit a document implies getting rid > of materials that are excellently written, displays deep knowledge, that > someone is very proud of, etc. simply because it does not fit or complicates > too much. > > That is not the process you have on the talk page. You must give this talk > to an editor, if need be a professional editor. Then your members can focus > the discussions on technical issues. > I don't understand why you can't just list this at the top-level discussion page then. The idea is just that it doesn't fit on Bugzilla, not that you need to make individual ones.
(In reply to Sam James from comment #5) > (In reply to Tormod Lunde from comment #4) > > (In reply to John Helmert III from comment #3) > > > I think you should provide that input at the relevant handbook talk page. > > > > Hi John, I have probably over 50 suggestions. I do not have the time to > > write them all into your discussion. But I can send them to someone. > > > > If you don't have time to write them, how can anyone have time to implement > them? > > > Also, if you need a discussion like that for every little revision, you will > > never arrive a neat little document. To edit a document implies getting rid > > of materials that are excellently written, displays deep knowledge, that > > someone is very proud of, etc. simply because it does not fit or complicates > > too much. > > > > That is not the process you have on the talk page. You must give this talk > > to an editor, if need be a professional editor. Then your members can focus > > the discussions on technical issues. > > > > I don't understand why you can't just list this at the top-level discussion > page then. The idea is just that it doesn't fit on Bugzilla, not that you > need to make individual ones. I have created a PDF of the document and commented in it, like an editor would. I have underlined errors, suggested sections to delete, sections to move, processes to improve. But that is all I will do. So if you want it, you can have it. But I am just a person wanting to install Gentoo, I am not one of the owners. And this has been a few hours, but it is all I will do. So it is a take it or leave it situation. Best, Tormod
(In reply to Tormod Lunde from comment #6) > (In reply to Sam James from comment #5) > > (In reply to Tormod Lunde from comment #4) > > > (In reply to John Helmert III from comment #3) > > > > I think you should provide that input at the relevant handbook talk page. > > > > > > Hi John, I have probably over 50 suggestions. I do not have the time to > > > write them all into your discussion. But I can send them to someone. > > > > > > > If you don't have time to write them, how can anyone have time to implement > > them? > > > > > Also, if you need a discussion like that for every little revision, you will > > > never arrive a neat little document. To edit a document implies getting rid > > > of materials that are excellently written, displays deep knowledge, that > > > someone is very proud of, etc. simply because it does not fit or complicates > > > too much. > > > > > > That is not the process you have on the talk page. You must give this talk > > > to an editor, if need be a professional editor. Then your members can focus > > > the discussions on technical issues. > > > > > > > I don't understand why you can't just list this at the top-level discussion > > page then. The idea is just that it doesn't fit on Bugzilla, not that you > > need to make individual ones. > > I have created a PDF of the document and commented in it, like an editor > would. I have underlined errors, suggested sections to delete, sections to > move, processes to improve. > You'd have to share the PDF then...? > But that is all I will do. So if you want it, you can have it. But I am just > a person wanting to install Gentoo, I am not one of the owners. And this has > been a few hours, but it is all I will do. So it is a take it or leave it > situation. OK.
