Date: Thu, 23 May 1996 19:58:13 -0700 From: "Jordan K. Hubbard" <jkh@time.cdrom.com> To: John Clark <jrclark@felix.iupui.edu> Cc: doc@freebsd.org Subject: Re: FAQ Contribution Message-ID: <5721.832906693@time.cdrom.com> In-Reply-To: Your message of "Thu, 23 May 1996 09:08:53 EDT." <2.2.32.19960523130853.006972e4@felix.iupui.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5721.832906693>