General remarks on the current state of the WD

I've done a quick pass over the current document, pretending to be  
someone interested in the subject (media fragments) but outside the  
group. In other words: exactly the type of person I think is the focus  
of our first WD.

I noticed a couple of things:
1. Of course, introduction needs to be written:-)
3. The use cases section needs a 1-paragraph introduction. "These are  
here 'cause we think media fragments should enable their  
implementation".
    Here the examples shouuld be <example>, because it isn't pre- 
formatted text.
    Usually, when using real-world names in scenarios, these people  
are defined up-front. This may be a bit much for this release, though.
    There are _very_ many scenarios. That's good for us, but around  
section 3.3 I started to lose interest and skipped ahead.
4. The one-line sections are tiring on the eyes. And again: there are  
so many and they all look alike, so after about 5 I got bored, and I  
had to force myself to continue reading.
    Image is missing in section 4.1. Also: we should not depend on the  
image only to define the single-timeline (think of blind people), this  
section needs a few more lines/
    4.3 and 4.4 seem to be in conflict with each other.
    4.5 I have no idea what this paragraph tries to say.
    4.8 this is impossible, as we've discovered by now.
    4.10 I have no idea what this tries to say.
5. Uses "addressing type" where section 7 uses "dimension". Need to  
pick a single word. It may be a good idea to add a glossary to the  
document, too (even if only to keep ourselves honest).
    Section 5.5 falls out of thin air. Also, the name is ambiguous (is  
it our solution that is fit, or the container?).
    Section 5.5 also breaks the logical flow of the document, I would  
be in favor of moving it to an appendix, with a 1- or 2-paragraph  
summary here. Also, the numbers in the table need to be replaced by  
something textual, or some easy to understand symbols, or something.
6. This is worse than 5.5. We go into an incredible amount of detail.  
Please move this to an appendix, or a chapter near the end of the  
document.
7. Names need to be the same as for section 5 (temporal vs. time).
    There's a bit of duplication (the dimensions), but it's only 1- 
liners so probably ok.
    I'm uncertain about 7.3 (ABNF). It's ugly here, we could put an  
excerpt or railroad-diagram here and move this to an appendix. But  
then: its only about a page or so, and it does contain details  
required for ull understanding.
    7.4 this is a hotch-potch that could use some structuring.
8. This states no approach is superior to the other. But nowhere are  
the approaches compared... Pro/Con table, maybe? Ah, this info is in  
8.3. Hmm, I think I would prefer it up front, but if it's going to be  
after the details there needs to be a forward ref here.
    Maybe the two images should go here, as a quick introduction of  
the difference between the two protocols. Oh yes: the images need an  
alt for blind viewers.
    Also, we may want to show an image here of what is sent back to  
the UA. Actually, the info in 8.2 (and 8.3) is incorrect: nowhere is  
it shown that the header is also transmitted.
    The whole chapter is even more coloquial than what I tend to  
write:-)
    8.3 Aside from what I said above, the discussion here about  
transcoding needs to go way up in the document. Section 4 or 5  
suggests itself.

--
Jack Jansen, <Jack.Jansen@cwi.nl>, http://www.cwi.nl/~jack
If I can't dance I don't want to be part of your revolution -- Emma  
Goldman

Received on Wednesday, 8 April 2009 08:55:55 UTC