From owner-freebsd-doc Mon Aug 5 9:23:23 2002 Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.FreeBSD.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7152937B400 for ; Mon, 5 Aug 2002 09:23:18 -0700 (PDT) Received: from mx2.datanet.hu (mx2.datanet.hu [194.149.13.163]) by mx1.FreeBSD.org (Postfix) with ESMTP id 98ADD43E6A for ; Mon, 5 Aug 2002 09:23:17 -0700 (PDT) (envelope-from sziszi@bsd.hu) Received: from fonix.adamsfamily.xx (nilus-1093.adsl.datanet.hu [195.56.92.77]) by mx2.datanet.hu (DataNet) with ESMTP id 2AE2358CE for ; Mon, 5 Aug 2002 18:23:15 +0200 (CEST) Received: from fonix.adamsfamily.xx (localhost [127.0.0.1]) by fonix.adamsfamily.xx (8.12.5/8.12.5) with ESMTP id g75GNCqI002221 for ; Mon, 5 Aug 2002 18:23:13 +0200 (CEST) (envelope-from sziszi@bsd.hu) Received: (from cc@localhost) by fonix.adamsfamily.xx (8.12.5/8.12.5/Submit) id g75GNCTa002220 for freebsd-doc@FreeBSD.ORG; Mon, 5 Aug 2002 18:23:12 +0200 (CEST) X-Authentication-Warning: fonix.adamsfamily.xx: cc set sender to sziszi@bsd.hu using -f Date: Mon, 5 Aug 2002 18:23:11 +0200 From: Szilveszter Adam To: freebsd-doc@FreeBSD.ORG Subject: Re: docs/41106: FreeBSD Handbook lacks "Desktop Applications" chapter. Message-ID: <20020805162311.GA2071@fonix.adamsfamily.xx> Mail-Followup-To: Szilveszter Adam , freebsd-doc@FreeBSD.ORG References: <3D4E7A4A.6080307@centtech.com> <200208051353.GAA15753@eskimo.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <200208051353.GAA15753@eskimo.com> User-Agent: Mutt/1.5.1i Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org Hello, On Mon, Aug 05, 2002 at 06:53:54AM -0700, Ross Lippert wrote: > If we had a 'port testimonials' area, which was fairly free form and > allowed each one of us to talk about how to get the most from kword, > abiword, openoffice, or whatever depending on which one each of us > lived in, then that would be more beneficial to the newbie. I think it > would be fun for all of us to share our experiences with our fav ports. I think this is a good idea. But on the other hand, this is not something that needs to be part of the official documentation, for a number of reasons. First is the bias, but this has already been discussed. Unfortunately, there is a "gently guiding towards the mainstream" effect in any event, since people generally tend to try apps base don others' recommendations when they are newbies and if they work they stick. (Because, ideally, computers are tools that you use to reach a certain aim, not an end in themselves) But if you use a mainstream app, chances are high that should you need help, you will find it. So, from a beginners point of view, this is a good thing. This takes us to the Second reason: Since writing up your experience in this way is entirely voluntary, there would be a wild variation of what would be and what wouldn't be covered. In somne categories, several apps would have almost equal coverage (whisper from the backroom: editor warssss) but in other categories, it would basically say: "use this app" and get done with it. Some categories would have no coverage at all since not many people use it. (and none of them bothered to do a writeup for us, saving it perhaps to a more professional audience) This would distort the picture needlessly: while we have over 6500 ports at present, only a fraction would even get a space in the limelight. Third reason: Maintenance. Even if you are very knowledgeable about an app, you can only tell the user about your experience with a particular version (or perhaps, some perspective on history). This very quickly becomes out-of-date. This even happens with FreeBSD itself: we are constantly on the lookout for sections of the documentation that are antiquated, yet they still get through. Any description, tips and tricks, and recommendations that you give in such a review may be outdated with the next version. To bring a FreeBSD example: under 3.x, the proper way to initialize your (ISA)PnP devices from the loader was one of the "tools of the trade" that was not documented well or at all yet it might have made the difference between a system that worked or that locked up upon the first boot. It even was a good method of disabling on-board components in favor of other hardware even if the BIOS did not support this, but I disgress. Today, this knowledge is pretty much useless. If you wrote up a review at that time passing on this (then) important piece of information and failed to maintain it, people might still judge FreeBSD by this and at the same time wondered why the trick didn't work any more. Apps that are in use in several differing major revisions (think bind 4.x, 8.x and 9.x) only make the matter worse. > The closest thing we have right now, is the 'trawling the ports > collection' series by Greg Lehey at ezine.daemonnews.org. But he's > one guy, writing monthly, and he doesn't always even have the time to > really trick out the programs he tries. Therefore I suggest that any such experience be gathered in a sort of diary, with exact version numbers and dates so that people could at once see what they are dealing with. Also, I have seen several "independent" FreeBSD sites spring up and then fade into oblivion during the years of hanging around this cornershop called "the FreeBSD project". This is normal since "one-man-shows" while a great ego-booster at first and good fun, may quickly grow unwieldy or take the back seat behind other aspect of an individual's life, if not get booted off the car altogether when they become inconvenient. (a typical example of this is the person leaving college/university) There is nothing more sad than a link page with dead links to non-existing pages or texts that are only gathering dust. This is why somebody once said on a FreeBSD mailing list (perhaps on -advocacy) that anybody offering documentation "independently" on their site without submitting it properly to the The FreeBSD Documentation Project and asking for a link should be compelled to maintain the availability of the URL for no less than 10 years from the date of submittal in order for the link to make any sense. While this may be a bit over the hump, you get the idea. Once a link is set, people generally don't care if it is alive. Therefore, I think that any such writeups should be submitted to outlets that have already proven themselves over time. One of these is DaemonNews, they are always on the look-out for articles. Not only Greg Lehey can write about his favorite ports, you can too. Submit it to articles@daemonnews.org and before you know, you could become a regular contributor! The DN site has an archive of all issues of the ezine ever published, so articles do not get lost and people can always see on what date they were current. The other such outlet is the FreeBSD Diary. (http://www.freebsddiary.org/). It has an astonishing number of articles that were gathered over time all searchable and available on-line. Although it started out as a one-person diary, there nothing preventing somebody to submit articles of their own. The advantage is that it does not have to be as polished as a newspaper article and may be more practically oriented (how-to style). The other advantage is that there is an opportunity for you to comment on the articles of others, so that you can tell how it could be done better. The comments appear at the bottom of the articles. Again, all articles have a date, so you can make a judgement about their currentness at the time of reading. So I would encourage everybody who has stories to tell here and now not to start yet another great-looking and dead in a year BSD site, but rather use these and other established outlets of the community which already offer what you just though about and perhaps more. Instead of linking dozens of one-page once-in-a-livetime :-) writeups it is also easier for the project to only link to these outlets and be confident that the links are helpful. -- Regards: Szilveszter ADAM Szombathely Hungary To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message