Date: Thu, 10 Jul 2014 08:22:40 -0600 (MDT) From: Warren Block <wblock@wonkity.com> To: Gavin Atkinson <gavin@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: Annotation for doc review Message-ID: <alpine.BSF.2.11.1407100727400.92272@wonkity.com> In-Reply-To: <alpine.BSF.2.00.1407101142190.44577@ury.york.ac.uk> References: <alpine.BSF.2.11.1407041441510.27613@wonkity.com> <alpine.BSF.2.00.1407101142190.44577@ury.york.ac.uk>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 10 Jul 2014, Gavin Atkinson wrote: > 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. The goal for this particular project is to have limited review events, kind of like a sprint. Limiting the scope to a particular section of documentation and limiting the time for review helps people know what to expect. Committers would volunteer ahead of time for the responsibility of going through the suggestions and changing the document, and know the limits of the project. This allows for budgeting time to make the changes. It's a fixed length rather than open-ended time commitment. Reviewers know that there is a deadline, and also that their suggestions will be considered immediately after that deadline. So there is an incentive to comment immediately. We can also announce these reviews to selected groups of users. A review of the Handbook X11 configuration section could be announced on the freebsd-x11 mailing list. These limited reviews could be used as test cases to see whether it could be used full-time on all docs. My concern is that someone would have to continuously monitor the comments and implement changes, or commenters could be discouraged. We have the beginnings that situation with doc bug reports now. > 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. It's technically possible, but again, monitoring that for suggestions would require a long-term commitment. Without that, users have less incentive to comment, and those that do comment could become discouraged without some kind of reasonably quick feedback. >> 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. There might also be anti-spam features in the annotation system, or they could be added. If we could use the same credentials as for Bugzilla, that would give people another reason to sign up. And it would be handy to be able to correspond by email with a commenter to ask them about details. It would be nice to be able to do this from the annotation web page: commenter leaves an unclear comment, committer clicks on a "respond by email" button, and it triggers a mailto link.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.11.1407100727400.92272>