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.
_______________________________________________
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"
