Date: Wed, 9 Jul 2014 13:54:57 -0400 From: John Baldwin <jhb@freebsd.org> To: freebsd-doc@freebsd.org Subject: Re: Annotation for doc review Message-ID: <201407091354.57645.jhb@freebsd.org> In-Reply-To: <alpine.BSF.2.11.1407041441510.27613@wonkity.com> References: <alpine.BSF.2.11.1407041441510.27613@wonkity.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201407091354.57645.jhb>