Date: Mon, 18 Feb 2002 15:15:51 -0800 From: bmah@freebsd.org (Bruce A. Mah) To: freebsd-doc@freebsd.org Cc: bmah@freebsd.org Subject: BSDCon Doc BoF Notes Message-ID: <200202182315.g1INFpc93221@bmah.dyndns.org>
next in thread | raw e-mail | index | archive | help
FreeBSD Documentation BOF 13 February 2001 Cathedral Hill Hotel, San Francisco, CA Notes by: Bruce A. Mah <bmah@freebsd.org> A few scribblings from the Doc BOF (typed up from my paper notes). In addition to myself, some people I remember being present (in no particular order) were: Murray Stokely, Nik Clayton, Paul Richards, Brian Somers, Bob Bruce, Chern Lee, Michael Lucas. Deep apologies to anyone whose names or presence I forgot (there's at least two of you). Murray presented some slides off his laptop (maybe he'll put them up somewhere?), beginning with some stats on commit activity. We had some brief discussion about the quality of translations of FDP documents, ending with the tentative conclusion that we just need to trust committers/translators to do the right thing. Murray: Infrastructure enhancements from the second print edition of the Handbook, such as index support (this needs to become better), print output enhancements (via Makefile variables), more content, typos fixed. Wants comments on the second edition. Mid-range plans: Optional XSLT toolchain support (as an option to our DSSSL-based toolchain), this will give us more flexibility and more choices (eventually) of tools. Experiment with XML manpages (lets us factor out duplicated material, e.g. tuning(7), and add semantic markup). Nik talked a bit about a proof of concept for the XML manpages; he thinks the way to go is to do an XML-to-mdoc translator because we can already do mdoc to output formats (i.e. ASCII, PostScript) without needing e.g. TeX in the base system. Problem is that XSLT processors we have (libxslt) only go from some XML-based representation to another XML-based representation. Bruce Mah: We still need the mdoc toolchain to handle manpages for ports. More mid-range plans: Split up the handbook. Issue here is to go to a lot of smaller books or a few larger ones. Lots of smaller books is like the Linux HOWTO project (Bob Bruce: Can we leverage the Linux HOWTOs? No solid answer to this.) Big books raise the barriers to entry for new contributers, and are hard to navigate (on the other hand, indexes are more useful). Paul Richards: Small books give us the ability to do incremental updates to printed documentation or at least make it more feasible. Another item: Find a better search engine for the Web site. Back to Murray's slides: Problems known with the second-edition Handbook: No sections on wireless networking or DVD/multimedia, IPsec section seems to be unusable by people who have tried to use it, grammar is horrible. Wants more constructive criticism, but people aren't giving much, not clear why. Michael Lucas: Many of the problems can be summed up as, "It's not enough to write to be understood; you have to write so that you cannot be misunderstood". Generally accepted that many contributors to the Handbook (many of whom are not professional writers) will cause this problem. Maybe needs a copy editor? Murray: PRs pointing out specific problems are welcomed, even if there's no patch. About this time, kicked out of the room by the next BOF. Corrections and/or alternate points of view welcomed! To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200202182315.g1INFpc93221>