Date: Sun, 7 Jan 2007 18:25:37 +0200 From: Giorgos Keramidas <keramida@ceid.upatras.gr> To: Steve Franks <stevefranks@ieee.org> Cc: freebsd-questions@freebsd.org Subject: Contributing to FreeBSD documentation (was: Re: no ath0 on new system with good card) Message-ID: <20070107162537.GB2261@kobe.laptop> In-Reply-To: <539c60b90701070754r33ba9ae8q6b22f96be0ab6ea0@mail.gmail.com> References: <539c60b90701060908o460d1d98wab2f2514a3a9d1e2@mail.gmail.com> <20070106202147.GB2532@kobe.laptop> <539c60b90701061849u35ddc61ch16a49484bd3baf12@mail.gmail.com> <20070107031750.GA5828@kobe.laptop> <539c60b90701070754r33ba9ae8q6b22f96be0ab6ea0@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On 2007-01-07 08:54, Steve Franks <stevefranks@ieee.org> wrote: > Apologies on not hitting the list. Alyays forget to reply-all. No problem. I just didn't copy the list because I wasn't sure I should. > So, I figured I'd try to fix the safe-mode end of things on my own, > and I found a post several years old (looked like it even could have > been yours) about safemode, which doesn't show up anywhere on the > freebsd site. So I did what it said and grep'd boot/beastie.4th for > safemode, which came up with this suprisingly total solution: > > add apic.0.disabled="1" to boot/device.hints. Not only does my system > come up in regular boot mode, but, as you suspected, the pccard works > too, so all appears well. Excellent news! Thanks for sharing the answer :) > So my final question, what in all the land is an "apic", "Advanced Programmable Interrupt Controller". This is the part of your system which assigns priorities to interrupt lines of a device. The full details are probably too technical for some percentage of our user base, but more details can be found at the following pages: http://en.wikipedia.org/wiki/Advanced_Programmable_Interrupt_Controller http://en.wikipedia.org/wiki/Programmable_Interrupt_Controller http://en.wikipedia.org/wiki/Intel_8259 http://en.wikipedia.org/wiki/Intel_APIC_Architecture > and why isn't apic or safemode mentioned in the handbook, manpages, or > even on the freebsd site? IIRC it is mentioned in the Developer's Handbook, but you are right that it should be in the main Handbook too. > Further, I'd like to write a handbook page on "freebsd and laptops", > because we're on my third one here now, and I'm starting to get the > drift of what could usefully be added to the handbook, namely a > thourough discussion of booting and device.hints. That would be great! If you can help writing such a section for the Handbook, a lot of users will be highly indebted to you, for sure :) > I presume someone 'peer-reviews' handbook submissions for correctness > and format? I recall reading somewhere about contributing, but I get > the impression you are involved enough to tell me whether it's a bad > idea or not. Yes, you are right. We have peer reviews. A lot of the documentation changes are filtered through the freebsd-doc mailing list, where documentation people hang out. Patches are mailed back and forth; edited; fixed for technical accuracy, syntax and grammar correctness; adapted to our writing style; expanded as necessary; and eventually committed to our documentation source code. You can definitely contribute as much as you feel, whenever you feel you have the time, and in any way you consider appropriate. We have a short article which describes how you can contribute to the FreeBSD Project, in general: http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributing/ Most of it applies directly to documentation too. Please skim through this article; it should be a good start. About your last question now... Yes, it's a good idea. Not just a good idea, though. It's an *excellent* idea. One of the "chicken and egg" problems documentation writing usually has to face is that: * New users don't know enough about the system, so they frequently pose good questions. These questions would result in higher quality documentation if properly channeled through experienced documentation writers, but you have to convince the new users that they can actually *help* by not knowing it all. * Once new users step over the thin line between being newcomers to the system and being experienced in some area, we have lost all the "insight" they can provide about how a new user thinks. As a result, it's easier to write documentation if we are targetting a very experienced, very technical audience. But, IMHO, the contributions of new users -- in the form of "interesting" questions" -- are at least as valuable, if not more :) Regards, Giorgos
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20070107162537.GB2261>