Date: Mon, 8 Jul 1996 17:10:10 GMT From: James Raynard <fdocs@jraynard.demon.co.uk> To: John Fieber <jfieber@indiana.edu> Cc: roberto@keltia.freenix.fr, jhs@freebsd.org, hoek@freenet.hamilton.on.ca, doc@freebsd.org Subject: Re: share/doc/FAQ/obj/freebsd-faq.html Message-ID: <199607081710.RAA01482@jraynard.demon.co.uk>
next in thread | raw e-mail | index | archive | help
> In the impending revolution with the handbook/FAQ processing > machinery, there is a great opportunity. Namely, I'm thinking of > a DTD tuned for FAQ use. It would use the same low level > elements as Docbook, but wrapped in an FAQ structure. If you > have any thoughts about what the ideal structure for the killer > FAQ would be, let me know! Much more sophisticated manipulation > of the document will be possible. Sorry for the delay in replying to this. There will probably be more suggestions later, but two that strike me immediately are:- 1. The TOC entries should be separated from the question and answer section. At the moment, we can either have long detailed questions, which make the TOC look untidy, or we can have terse questions, which new users may find difficult to relate to their particular problem. Separating them would allow us to put terse summaries in the TOC, so that experienced users can look things up quickly, while the questions themselves can be more discursive and ``redundant'', describe problem symptoms in detail, etc. Also, this would allow the same question to appear in different forms in the TOC (eg ``How do I get a PS/2 mouse to work with FreeBSD?'' and ``How do I get my laptop's trackerball to work with FreeBSD?'' would both lead to the instructions on configuring a kernel with PS/2 support). 2. I don't know how feasible this is, but it would be really good to have some way of identifying keywords for an indexing program. For example, in the above example, ``laptop'', ``mouse'' and ``kernel'' would be keywords; a user with a laptop could go to a ``search the FAQ'' page, type in ``laptop'' and get this entry and all the other laptop-related pitfalls and handy hints in the FAQ. Or they could type in ``laptop and mouse'' to find out how to use their laptop mouse with FreeBSD. -- James Raynard, Edinburgh, Scotland james@jraynard.demon.co.uk http://www.freebsd.org/~jraynard/
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?199607081710.RAA01482>