Re: [virtio] how should people comment on spec (was Re: [virtio-comment]

Subject: Re: [virtio] how should people comment on spec (was Re: [virtio-comment] VIRTIO Spec feedback)

Hi Rusty, hi Michael,

You can certainly add line numbers if you like. Many TCs do that. You can also suggest that people use a particular version (source, pdf, html) for commenting although reviewers are free to choose what source they want to review. You can also provide suggestions for how best people can express comments (e.g. "Please identify the location of the text on which you are commenting by..."). What I suggest is that you provide any description along those lines that you'd like reviewers to use and I will incorporate it into the announcement of the public review. E.g. "The TC requests that reviewers provide comments against the xxxx verion and ..."

I am also working on a script that will put a little comment link next to each heading in the HTML version of the file and, when clicked, will start an email message to the -comment@ mailing list with the section # and title in the subject line. That should be ready soon and should help focus review comments more closely.

I'm not so keen on the idea of pointing reviewers *away* from the csprd version of the spec on docs.oasis-open.org and into the SVN or other working draft locations. Rather, we can point people to the editable source files packaged with the release and ask them to work from those.

Rusty, by "patches" do you mean that reviewers could send revised tex back to the TC? That would certainly be ok too so long as it came through virtio-comment@ mailing list.

Best,

/chet

On Thu, Feb 6, 2014 at 7:50 PM, Rusty Russell <rusty@au1.ibm.com> wrote:

"Michael S. Tsirkin" <mst@redhat.com> writes:
> By the way, guys - how are people supposed to comment on spec?
>
> Several people failed to figure it out and just
> sent me bits of text copy-pasted from pdf,
> really hard to read.
>
> Transcribe "on page X line Y ..."?
> Could be possible if we at least numbered lines.
>
> Chet - is this allowed in specs?
>
> It's still pretty painful.
> Use some tool to add notes to PDF?
> I don't know of one, and then it's still hard to find
> and read the notes.
>
> I think for next draft revision we should
> make more public our svn tree location and location
> of source in zip file, and tell people how to comment
> on tex and how to subscribe to the mailing list
> if they want to.
>
> Chet - any objections?

Agreed. While we've nominated the PDF as canonical, there's no reason
they can't comment against the other variants.

For WD02 I'd like to add line numbers if we can, and definitely point
people to the tex source for in-depth commenting (even patches!).

Thanks,
Rusty.

--

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

Check your work using the Support Request Submission Checklist at http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html

TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin

Follow OASIS on:
LinkedIn: http://linkd.in/OASISopen
Twitter: http://twitter.com/OASISopen
Facebook: http://facebook.com/oasis.open

virtio message