Re: Annotation for doc review
On Fri, 4 Jul 2014, Warren Block wrote: 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. 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/ I'd be very happy to see something like this. Note that I am not suggesting this would go on our documentation web pages. Could you elaborate as to why you think this is a bad idea? I think a significant part of the benefit is receiving comments from people who only drop into the documentation for a few seconds and then vanish again. These are the sort of people who are unlikely to go out of their way to reiew docs for us, but might leave a comment if there was an easy mechanism to do so. PostgreSQL used to have a facility to comment directly on the web page, though they seem to have instead moved to a forum approach. Could we also consider that perhaps? I don't know how easy it would be for every page to have its own section on the forum, but maybe that could work? Though I do very much prefer their old approach, to be honest. 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 To some extent, we only need to avoid spam if the suggestions are not immediately published. If there is some moderation process before they become visible, that would likely be suficient. Gavin ___ 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
Re: Annotation for doc review
On Thu, Jul 10, 2014 at 11:49:26AM +0100, Gavin Atkinson wrote: PostgreSQL used to have a facility to comment directly on the web page, though they seem to have instead moved to a forum approach. Please, no. Glen pgpka7Bo6CNyJ.pgp Description: PGP signature
Re: Annotation for doc review
On Thu, 10 Jul 2014, Glen Barber wrote: On Thu, Jul 10, 2014 at 11:49:26AM +0100, Gavin Atkinson wrote: PostgreSQL used to have a facility to comment directly on the web page, though they seem to have instead moved to a forum approach. Please, no. To which half? G ___ 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
Re: Annotation for doc review
On Thu, Jul 10, 2014 at 12:15:36PM +0100, Gavin Atkinson wrote: On Thu, 10 Jul 2014, Glen Barber wrote: On Thu, Jul 10, 2014 at 11:49:26AM +0100, Gavin Atkinson wrote: PostgreSQL used to have a facility to comment directly on the web page, though they seem to have instead moved to a forum approach. Please, no. To which half? Forum approach. Glen pgpvTSd4K4Oqh.pgp Description: PGP signature
Re: Annotation for doc review
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
