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 _______________________________________________ freebsd-doc@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"