From owner-freebsd-doc@FreeBSD.ORG Wed Jul 9 20:41:01 2014 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 05F14949 for ; Wed, 9 Jul 2014 20:41:01 +0000 (UTC) Received: from bigwig.baldwin.cx (bigwig.baldwin.cx [IPv6:2001:470:1f11:75::1]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id D4F5F27C1 for ; Wed, 9 Jul 2014 20:41:00 +0000 (UTC) Received: from jhbbsd.localnet (unknown [209.249.190.124]) by bigwig.baldwin.cx (Postfix) with ESMTPSA id E3632B9C1; Wed, 9 Jul 2014 16:40:59 -0400 (EDT) From: John Baldwin To: freebsd-doc@freebsd.org Subject: Re: Annotation for doc review Date: Wed, 9 Jul 2014 13:54:57 -0400 User-Agent: KMail/1.13.5 (FreeBSD/8.4-CBSD-20140415; KDE/4.5.5; amd64; ; ) References: In-Reply-To: MIME-Version: 1.0 Content-Type: Text/Plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Message-Id: <201407091354.57645.jhb@freebsd.org> X-Greylist: Sender succeeded SMTP AUTH, not delayed by milter-greylist-4.2.7 (bigwig.baldwin.cx); Wed, 09 Jul 2014 16:41:00 -0400 (EDT) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 09 Jul 2014 20:41:01 -0000 On Friday, July 04, 2014 4:54:42 pm Warren Block wrote: > The phabricator instance has shown that some review can be done more > easily. > > We've talked before about having periodic reviews of parts of the > documentation. It turns out that experts rarely read the docs on things > they know about, but are the ones that can produce very valuable > feedback. > > Phabricator probably does not lend itself well to reviewing our DocBook > documents. The source and rendered versions are just too different to > review easily, even for those who are familiar with DocBook. > > Ideally, we'd be able to show a rendered HTML version of the document > and let people comment on it. Definitely agreed. > There are commercial services out there for that, but also free > Javascript implementations that we could use directly, like this: > > http://annotatorjs.org/ > > Note that I am not suggesting this would go on our documentation web > pages. Instead, we would create a small rendered version of part of a > document, say one subsection out of a chapter, and put that up somewhere > for review and annotation. At the end of a limited time, maybe a week > or two, the annotations would be gone through, adapted, and changes > applied. Then the process is repeated for a different documentation > section. The annotated web page is just temporary. > > The biggest problems I see are > > user authentication: so we can avoid spam and vandalism, and track > suggestions by user. For best results, this would use existing > credentials and not require creating a new account Talk with clusteradm@ about the setup they use for bugzilla (and I believe are going to adopt for phabric) > logging: annotations must be saved until they can be processed > > If these problems can be addressed, we can make it doc review easy for > everyone. This sounds like an excellent idea. -- John Baldwin