From owner-freebsd-doc Mon Jul 1 13:20:54 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id NAA04993 for doc-outgoing; Mon, 1 Jul 1996 13:20:54 -0700 (PDT) Received: from vector.jhs.no_domain (slip139-92-42-157.ut.nl.ibm.net [139.92.42.157]) by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id NAA04976 for ; Mon, 1 Jul 1996 13:20:37 -0700 (PDT) Received: (from jhs@localhost) by vector.jhs.no_domain (8.7.5/8.6.9) id SAA13589; Mon, 1 Jul 1996 18:33:55 +0200 (MET DST) Date: Mon, 1 Jul 1996 18:33:55 +0200 (MET DST) Message-Id: <199607011633.SAA13589@vector.jhs.no_domain> To: doc@freebsd.org Subject: share/doc/FAQ/obj/freebsd-faq.html From: "Julian H. Stacey" Reply-To: "Julian H. Stacey" Organization: Vector Systems Ltd. Address: Holz Strasse 27d, 80469 Munich, Germany Phone: +49.89.268616 Fax: +49.89.2608126 (later) Web: http://www.freebsd.org/~jhs/ Mailer: EXMH 1.6.7, PGP available Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk Based on current src/ Quick Suggestion: Add clickable HREFs right at end of freebsd-faq.html for - Questions (mailto:questions@freebsd.org) - FAQ Errors, (mailto: doc editors) Style & Colloquialisms: 7.3. Hey! Chmod ... 7.6. Hey! My printer is slow as a dog ... This style makes the FAQ harder to quickly scan when people look to see if a question is in the FAQ before posting. The harder the FAQ index is to visually scan, the more postings we'll get. I suggest changes such as: s/Hey! Chmod/Chmod/ s/7.6. Hey! My printer is slow as a dog/ 7.6. Printer too slow: how to speed it up./ Colloquial `slow as a dog' is fine for native English speakers, but is it obvious to a Chinese or Brazilian etc ? Some dogs are fast (`Imperialist running dogs' at least :-) maybe some people will find `as slow as a dog' non obvious. Daft answers don't deserve to clutter the index & waste space forever: Delete: `7.20. Has anyone done any temperature testing.....' the question is debatable, the answer is just wasted space. Delete `7.21 ...memory to make a scratchy sound?...' The answer is wasted space, & doesnt even mention the floppy media sensing head seeks in the bios. Longer Term Suggestion: Reorder the words in the FAQ sections titles, similar to the way a stores list of engineering components is listed, so that the index is visually scannable fast & easily. EG: Printer, colour, driver: fails when blah blah Printer, postscript: filters available Printer, parallel port: interrupt config Printer, serial: interface parameters Changes would require some small departure from the traditional net news FAQ format, but that was typically just a collection of Q & A's slung together by one person. The FreeBSD FAQ in sgml format with HREFs & lots of readers could perhaps benefit from a more rigorous indexed format, stripped of surplus entries, phrases words ? This is intended as constructive criticism, hoping not to annoy anyone, Yes, I too find the FAQ useful even as is, Thanks :-) PS I've appended no diffs, as it's a style issue, in the hands of those commiters who work on the FAQ. PS I'm not on docs@ list, (in case cc line is pruned later). Julian -- Julian H. Stacey jhs@freebsd.org http://www.freebsd.org/~jhs/