AOMediaCodec / iamf

Immersive Audio Model and Formats
https://aomediacodec.github.io/iamf/
79 stars 15 forks source link

Improve the introduction #95

Closed cconcolato closed 1 year ago

cconcolato commented 2 years ago

The introduction could be improved:

I suggest restructuring as follows:

I don't think we need to list the rest of the specification. This is error prone and the specification already contains a table of content on the side.

As a result, section 1 and 2 should be merged and only 1 section "Introduction" should be used.

sunghee-hwang commented 1 year ago

It would be better to take this action after most of the spec texts are cleared.

tdaede commented 1 year ago

I do want to leave this open just because although most of this has been fixed by #95, I do think the introduction is a bit abrupt now and could use maybe one more pass.

cconcolato commented 1 year ago

Here are some high level suggestions to improve the introduction:

My main concern is that the introduction explains the "how" (model, syntax), without giving an indication of the "why". It should contain examples of how to instantiate the model for typical IAMF use cases, from the most simple use case (1 Mix Presentation, 1 Audio Element, 1 or N substreams to achieve speaker layouts that are badly addressed today) to most complex examples.

The specification should start with the introduction rather than with the conventions. The reader is more interested in understanding what the spec is about rather than what conventions were used. I would move the convention section to the end of the spec, maybe with a sentence in the current section 3 saying that conventions are described in section X, providing a hyperlink to it.

Some more detailed comments below: Before Section 2.1

Section 2.2.1

Section 2.2.2

sunghee-hwang commented 1 year ago

@cconcolato, thank you for your wonderful suggestions to improve its readability. Let me take this action after resolving technical issues which are related to Ref. S/W implementation. Anyway, the shape would be like this.