OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

virtio message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


Hi Chet,

        All good advice.  I'll add an agenda point to the next meeting,
that we should make the TeX source (as packaged) the canonical version,
and provide comment guidence like so:

1) An ideal comment is in the form of a patch against the TeX source.

2) Second best is a simple email quoting the spec, then making comment
   or suggestions, eg:

        In 4.1.3.1.1 Virtio Device Configuration Layout:
                ... Virtio Device Configuration Layout includes many
                entertaining anecdotes

        This should read be "several anecdotes", since most were
        not amusing.

3) But we'd prefer to have feedback in any form, rather than no
   feedback!

Thanks,
Rusty.

Chet Ensign <chet.ensign@oasis-open.org> writes:
> 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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]