What to improve in the specifications to make it more developer friendly?

[dsilhavy]

The idea of this thread is to collect ideas on how to improve the existing 3GPP specifications to make them more developer friendly. Please post any ideas you have that would make implementation easier.

• Anything you are missing in the specifications?
• Anything that could be improved?
• Anything that helps you get started more easy?

[dsilhavy]

Some unsorted ideas:

• Examples including concrete calculations and what to do with specific values
  • DASH example:
    ProducerReferenceTime: https://github.com/Dash-Industry-Forum/dash.js/pull/3895#issuecomment-1076465858
  • DASH-IF IOP guidelines provide good examples for instance different media time information of segments (3.2.11)
• For 3GPP/5G: Lots of different specifications, documents that provide a use-case oriented summary including the reference to the required specifications.
  • Recommended reading order
  • Highlight specific Annex?
  • Add specification number to the interfaces in the diagrams
• Potentially more use-case oriented in the introduction for better understanding
  • Example: https://github.com/5G-MAG/Documentation-and-Architecture/wiki/Use-Case:-HLS-playback-over-5G-Broadcast
  • Probably already included everywhere as an annex?
• Include all abbreviations in the beginning, ETSI 103720 is a good example
• Sequence diagrams - seem to be available in most cases
• (Direct reference to concrete APIs such as MSE, EME, Android SDK?)
• Annotation of statements such as “shall”
  • Specification version
  • Section number
• Consultation: Offer the possibilities for developers to reach out to the authors of the specification. DASH-IF, 5G-MAG have a good model here.

[dsilhavy]

Some additional feedback from our developer's call on Friday 8th April:

• Klaus:
  • Recommendation for reading. Can be useful but lots of stuff to read.
  • Looking back the experience from implementing the receiver
    • zip files of Word documents with separate chapters, can be slow and hard to maintain
    • central repo that is full text searchable, many things are cross-referenced
  • Slow Word documents, searching is hard
  • Richard
    • Turned Word documents into pdfs
    • ETSI NWM
      • Move away from Word
      • Online platform, presumable search everything on this platform
  • Klaus
    • Couple together a platform that has all the files
• Johann
  • Interactive specifications would be great: Popups, search
• Abbreviations are available:
• TR 21905
• https://webapp.etsi.org/Teddi