Date: Mon, 28 Aug 1995 03:28:38 -0700 From: "Jordan K. Hubbard" <jkh@time.cdrom.com> To: doc@freebsd.org Cc: hackers@freebsd.org Subject: Argh. I think we need to do a quick reality-check on our docs.. Message-ID: <2872.809605718@time.cdrom.com>
next in thread | raw e-mail | index | archive | help
I was responding to a user's message on the net today and he was having some trouble with the 3C509 ethernet card. "Aha!" says I. "I remember seeing something about this somewhere from Rod and it's in the docs, so I'll just point him at it!" Famous last words. I couldn't _find_ the bleedin' reference! After searching through the handbook and the FAQ, I came to two very quick conclusions: 1. There is a lot of redundancy between the two. 2. We really really need a permuted index!! If it's this much trouble for _me_ to find things, and I'm supposed to sort of know the lay of the land here, just imagine how hard it is for the poor user! I don't mean to sound like I'm whining, but this is a real problem and I'm coming to rely more and more heavily on the docs as the 2.1 install comes closer. Most people probably don't know that the 2.1 installation will have Lynx on the boot floppy and use it for browsing ALL the doc! This means that what's on the floppy will no longer be something that comes out of /usr/src/release/sysinstall/help/..., it will be a subset of the handbook itself! This was necessary due to the fact that much of sysinstall/help/* wound up migrating straight into the handbook and there's just no sense in maintaining two versions. We also need to bring the foreign-language versions over so that all that work isn't lost, and I daresay that John Fieber could use some help here! I hate to make this "help us with the docs, please!" plea so often in -hackers, but the docs really are becoming a significant keystone in how FreeBSD is presented, from install time onwards, and we ALL need to start taking them much more seriously! I think that this is a good thing since the docs will never really mature and grow without some "serious mission in life" like providing the initial install documentation, but putting this degree of pressure on them also has its price. Could I get some volunteers for the following projects? 1. Fill in the *'d topics in the Handbook. Some people have told me that they'd like to help with the docs if they just knew what needed doing, and I'd say that John has made it pretty clear at a glance if you just take a look at http://www.freebsd.org/Handbook and see which items have asterisks next to them. If you take a `*'d item, please also send a note to doc@FreeBSD.org so that work isn't unnecessarity duplicated. Please don't take something you won't finish, since by "adopting" it you're also essentially dissuading anyone else from doing so! 2. Look at /usr/src/release/sysinstall/help/${LANG}/* and see if you can help John create a language-specific section for whichever language it is you're most interested in. This is not only helpful to the multi-lingual boot floppy work but also helps our effort to eventually have versions of the Handbook available in multiple languages! Wouldn't you like to see future versions of the handbook available in German, French, Spanish or Russian? In time I may even have WC talked into printing a version of the handbook as an inside booklet in the CD, and I see no reason why country-specific versions of the CD shouldn't be produced. If you can sell a few thousand, say, spanish editions of the CD then it more than pays for the I18N work. This makes the local spanish market pretty happy too, so everyone wins. However, whether or not we get all of these nifty things really sort of depends on us, and only us, for now. I personally am really enthusiastic about the prospect of all of this coming together, but I know that neither John nor I have sufficent time to do all the work necessary. I'd like to keep myself focused on the boot floppy end of things so that we have a reasonable chance of the whole idea _working_ in the install, and I think John would probably like to look at the design issues surrounding the handbook as a whole (and in particular, I'm going to need his help with the production of the boot floppy version of the handbook) so that keeps him pretty busy. So. anyway... In case you didn't feel like reading all of the above, it can also be summarized as: "Help! Help! Help! Fire in docs! People with big feet needed!" Jordan
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?2872.809605718>