From owner-freebsd-doc@FreeBSD.ORG Fri Jul 4 20:54:50 2014 Return-Path: Delivered-To: freebsd-doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 1A90895C for ; Fri, 4 Jul 2014 20:54:50 +0000 (UTC) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "wonkity.com", Issuer "wonkity.com" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id BE1AA20F8 for ; Fri, 4 Jul 2014 20:54:49 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.9/8.14.9) with ESMTP id s64Ksg1A030786 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Fri, 4 Jul 2014 14:54:42 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.9/8.14.9/Submit) with ESMTP id s64Ksg49030783 for ; Fri, 4 Jul 2014 14:54:42 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Fri, 4 Jul 2014 14:54:42 -0600 (MDT) From: Warren Block To: freebsd-doc@FreeBSD.org Subject: Annotation for doc review Message-ID: User-Agent: Alpine 2.11 (BSF 23 2013-08-11) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Fri, 04 Jul 2014 14:54:42 -0600 (MDT) 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: Fri, 04 Jul 2014 20:54:50 -0000 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. 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 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.