Proposed documentation structure

[garethsb]

Here is a proposed documentation structure, reflecting that the v1.0 specification currently assumes implementers and users to have knowledge of best practice and idioms defined in prior AMWA NMOS specifications such as IS-04 and IS-05.

The additional documentation is entirely clarification of existing function and behaviour in v1.0.

1.0. Overview

• move final two or three paragraphs of Introduction and Class diagram to a new 3.0. Data Model doc (below)
• add direct links to 2.0 APIs and 3.0 Data Model

2.0. APIs (new)

• based on IS-04 APIs or IS-05 APIs docs

2.1. APIs - Client Side Implementation (new) 2.2. APIs - Server Side Implementation (new)

• these also based on e.g. IS-05 APIs - Server Side Implementation Notes

2.3. APIs - Query Parameters (new)

• based on IS-04 APIs - Query Parameters to resolve #25 and related concerns about the current RAML spec for netctrl Pagination and Basic Query Parameters

3.0. Data Model (new)

• with overview moved from 1.0. Overview as mentioned above

3.1. Endpoint (moved from 2.0. Endpoint) 3.2. Network Flow (moved from 3.0. Network Flow) 3.3. Network Device (moved from 4.0. Network Device) 3.4. Network Link (moved from 5.0. Network Links)

3.5. Identifier Generation (new)

• I think a short section is warranted to resolve #23, potentially with some words based on IS-04 Data Model - Identifier Mapping

---

Thoughts? @vsachin33 @andrewbonney @peterbrightwell

[andrewbonney]

Sounds good to me

[peterbrightwell]

Looks good -- the more we can match the structure of the other IS's the better for the future.