From owner-freebsd-doc Thu May 23 19:58:27 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.3/8.7.3) id TAA28529 for doc-outgoing; Thu, 23 May 1996 19:58:27 -0700 (PDT) Received: from time.cdrom.com (time.cdrom.com [204.216.27.226]) by freefall.freebsd.org (8.7.3/8.7.3) with ESMTP id TAA28515 for ; Thu, 23 May 1996 19:58:23 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by time.cdrom.com (8.7.5/8.6.9) with SMTP id TAA05723; Thu, 23 May 1996 19:58:13 -0700 (PDT) To: John Clark cc: doc@freebsd.org Subject: Re: FAQ Contribution In-reply-to: Your message of "Thu, 23 May 1996 09:08:53 EDT." <2.2.32.19960523130853.006972e4@felix.iupui.edu> Date: Thu, 23 May 1996 19:58:13 -0700 Message-ID: <5721.832906693@time.cdrom.com> From: "Jordan K. Hubbard" Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk > Anyway, I have written a FAQ to be added on this subject. I see no FAQ > regarding "How to use the ports collection." I would like to submit it, and I think the biggest issue here is that there's a lot more than a FAQ entry's worth of material here. A FAQ entry, by its very nature, should be a paragraph or less long. Its only job is to give you "reasonable answers" to high-level questions like "where do I find application software?" or "how can I find out more about the ports collection?" It's the second part of that FAQ entry that really requires some serious sit-down thought. For example, we don't just want to document one part of the user approach to ports problem, we want to have one document with multiple sections where you can come to find out more than you'd ever want to know about the ports collection, from a quick walk-through to an in-depth "how to create ports of your own" section. It's also important to have the grand design for all these bits in your mind at the start, before much is written, or you wind up with lots of disconnected "howto" sorts of documents in which no consistent style is followed. You see a lot of this in the handbook today, as you're jumped back and forth from "expert" to "dummy" mode and the authors' personal styles shift confusingly between relaxed and rigid. If we had a professional tech-writer working for us, he/she would probably cluck over the thing for awhile and think "rewrite!" :-) Jordan