From owner-doc-jp-work@jp.FreeBSD.org Tue Feb 19 14:22:42 2002
Received: (from daemon@localhost)
	by castle.jp.FreeBSD.org (8.11.6+3.4W/8.11.3) id g1J5MgI74841;
	Tue, 19 Feb 2002 14:22:42 +0900 (JST)
	(envelope-from owner-doc-jp-work@jp.FreeBSD.org)
Received: from eos.ocn.ne.jp (eos.ocn.ne.jp [210.190.142.171])
	by castle.jp.FreeBSD.org (8.11.6+3.4W/8.11.3) with ESMTP/inet id g1J5MfW74836
	for <doc-jp-work@jp.FreeBSD.org>; Tue, 19 Feb 2002 14:22:41 +0900 (JST)
	(envelope-from hrs@eos.ocn.ne.jp)
Received: from mail.hrslab.yi.org (p0775-ip01funabasi.chiba.ocn.ne.jp [61.119.148.13])
	by eos.ocn.ne.jp (OCN) with ESMTP id OAA21589
	for <doc-jp-work@jp.FreeBSD.org>; Tue, 19 Feb 2002 14:22:40 +0900 (JST)
Received: from localhost (alph.hrslab.yi.org [192.168.0.10])
	by mail.hrslab.yi.org (8.9.3/3.7W/DomainMaster) with ESMTP id OAA58970
	for <doc-jp-work@jp.FreeBSD.org>; Tue, 19 Feb 2002 14:22:15 +0900 (JST)
	(envelope-from hrs@eos.ocn.ne.jp)
Date: Tue, 19 Feb 2002 14:21:49 +0900 (JST)
Message-Id: <20020219.142149.88473186.hrs@eos.ocn.ne.jp>
To: doc-jp-work@jp.FreeBSD.org
From: Hiroki Sato <hrs@eos.ocn.ne.jp>
X-Mailer: Mew version 2.1 on Emacs 20.7 / Mule 4.0 (HANANOEN)
Mime-Version: 1.0
Content-Type: Multipart/Mixed;
 boundary="--Next_Part(Tue_Feb_19_14:21:49_2002_288)--"
Content-Transfer-Encoding: 7bit
Reply-To: doc-jp-work@jp.FreeBSD.org
Precedence: list
X-Distribute: distribute version 2.1 (Alpha) patchlevel 24e+011218
X-Sequence: doc-jp-work 159
Subject: [doc-jp-work 159] Fw: BSDCon Doc BoF Notes
Errors-To: owner-doc-jp-work@jp.FreeBSD.org
Sender: owner-doc-jp-work@jp.FreeBSD.org
X-Originator: hrs@eos.ocn.ne.jp

----Next_Part(Tue_Feb_19_14:21:49_2002_288)--
Content-Type: Text/Plain; charset=iso-2022-jp
Content-Transfer-Encoding: 7bit

$B:4F#!wEl5~M}2JBg3X$G$9!#(B

 bmah@ $B$,(B Doc BoF $B$N%5%^%j$r=P$7$F$^$9$N$G!"(B
 $BG0$N$?$a(B doc-jp-work $B$K$b(B forward $B$7$H$-$^$9!#(B

--
| $B:4F#(B $B9-@8!wEl5~M}2JBg3X(B <hrs@eos.ocn.ne.jp>
|                         <hrs@FreeBSD.org> (FreeBSD Project)

----Next_Part(Tue_Feb_19_14:21:49_2002_288)--
Content-Type: Message/Rfc822

Return-Path: owner-freebsd-doc@FreeBSD.ORG
Received: from castle.jp.FreeBSD.org (castle.jp.FreeBSD.org [210.226.20.15])
	by eos.ocn.ne.jp (OCN) with ESMTP id IAA28905
	for <hrs@eos.ocn.ne.jp>; Tue, 19 Feb 2002 08:16:13 +0900 (JST)
Received: from mx2.freebsd.org (mx2.FreeBSD.org [216.136.204.119])
	by castle.jp.FreeBSD.org (8.11.6+3.4W/8.11.3) with ESMTP/inet id g1ING1W81850;
	Tue, 19 Feb 2002 08:16:01 +0900 (JST)
	(envelope-from owner-freebsd-doc@FreeBSD.ORG)
Received: from hub.freebsd.org (hub.FreeBSD.org [216.136.204.18])
	by mx2.freebsd.org (Postfix) with ESMTP
	id 6BE5055D96; Mon, 18 Feb 2002 15:09:30 -0800 (PST)
	(envelope-from owner-freebsd-doc@FreeBSD.ORG)
Received: by hub.freebsd.org (Postfix, from userid 538)
	id 4F42837B400; Mon, 18 Feb 2002 15:15:58 -0800 (PST)
Received: from localhost (localhost [127.0.0.1])
	by hub.freebsd.org (Postfix) with SMTP
	id 45D752E800C; Mon, 18 Feb 2002 15:15:58 -0800 (PST)
Received: by hub.freebsd.org (bulk_mailer v1.12); Mon, 18 Feb 2002 15:15:58 -0800
Delivered-To: freebsd-doc@freebsd.org
Received: from rwcrmhc52.attbi.com (rwcrmhc52.attbi.com [216.148.227.88])
	by hub.freebsd.org (Postfix) with ESMTP
	id 2AA0C37B41B; Mon, 18 Feb 2002 15:15:52 -0800 (PST)
Received: from bmah.dyndns.org ([12.233.149.189]) by rwcrmhc52.attbi.com
          (InterMail vM.4.01.03.27 201-229-121-127-20010626) with ESMTP
          id <20020218231551.JVZQ1147.rwcrmhc52.attbi.com@bmah.dyndns.org>;
          Mon, 18 Feb 2002 23:15:51 +0000
Received: (from bmah@localhost)
	by bmah.dyndns.org (8.11.6/8.11.6) id g1INFpc93221;
	Mon, 18 Feb 2002 15:15:51 -0800 (PST)
	(envelope-from bmah)
Message-Id: <200202182315.g1INFpc93221@bmah.dyndns.org>
X-Mailer: exmh version 2.5 07/13/2001 with nmh-1.0.4
To: freebsd-doc@FreeBSD.ORG
Cc: bmah@FreeBSD.ORG
Subject: BSDCon Doc BoF Notes
From: bmah@FreeBSD.ORG (Bruce A. Mah)
Reply-To: bmah@FreeBSD.ORG
X-Face: g~c`.{#4q0"(V*b#g[i~rXgm*w;:nMfz%_RZLma)UgGN&=j`5vXoU^@n5<Pi&akO)o^8;[r
 %l(8ZHlbF`dD>v4:OO)c["!w)nD/!!~e4Sj7LiT'6*wZ83454H""lb{CC%T37O!!'S$S&D}sem7I[A
 2V%N&+
X-Image-Url: http://www.employees.org/~bmah/Images/bmah-cisco-small.gif
X-Url: http://www.employees.org/~bmah/
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Date: Mon, 18 Feb 2002 15:15:51 -0800
Sender: owner-freebsd-doc@FreeBSD.ORG
List-ID: <freebsd-doc.FreeBSD.ORG>
List-Archive: <http://docs.freebsd.org/mail/> (Web Archive)
List-Help: <mailto:majordomo@FreeBSD.ORG?subject=help> (List Instructions)
List-Subscribe: <mailto:majordomo@FreeBSD.ORG?subject=subscribe%20freebsd-doc>
List-Unsubscribe: <mailto:majordomo@FreeBSD.ORG?subject=unsubscribe%20freebsd-doc>
X-Loop: FreeBSD.org
Precedence: bulk

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


----Next_Part(Tue_Feb_19_14:21:49_2002_288)----
