Table layout

[duncandewhurst]

I'm sharing some feedback from @lgs85, originally posted in Open-Telecoms-Data/open-fibre-data-standard#252 (comment)

---

I wonder if we can also update how the reference tables are formatted? The existing approach, which uses two rows per object, is very confusing in my opinion:

Title	Description	Type	Format	Required
id		string	uuid	Required
Identifier	A universally unique identifier for this network, as defined by RFC 4122. For more information, see the identifier reference.
name		string
Network name	A name for this network.
nodes		array[Node]
Nodes	Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless: The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in .links The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in .links. For more information, see how to format data for publication. See Node

In addition to the structural issue, I'm not convinced about the utility of title. Something like this is clearer I think:

Field	Description	Type	Format	Required
id	A universally unique identifier for this network, as defined by RFC 4122. For more information, see the identifier reference.	string	uuid	Required
name	A name for this network.	string
nodes	Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless: The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in .links The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in .links. For more information, see how to format data for publication. See Node	array[Node]

If we want to keep title, it could look like this, though this is a little unweildy:

Field	Title	Description	Type	Format	Required
id	Identifier	A universally unique identifier for this network, as defined by RFC 4122. For more information, see the identifier reference.	string	uuid	Required
name	Network name	A name for this network.	string
nodes	Nodes	Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless: The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in .links The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in .links. For more information, see how to format data for publication. See Node	array[Node]

[jpmckinney]

Title is important to OCDS and any other JSON Schema where the title adds a little more to the field name.

Format and/or Required can be combined with Type, to decrease the column count.

[Bjwebb]

I think part of the reason we ended up with the current layout, was due to how wider tables were handled by the theme. We could check whether that's still a problem with Furo.

We could have multiple layouts behind different options, to accommodate the needs of different standards.

[jpmckinney]

Are you using furo for new standard docs? I've been looking at the pydata-theme. The top navigation bar helps decrease the menu depth, since you can use it for Primer, Guidance, Reference, and then put second-level navigation on the left (and within-page navigation on the right).

[lgs85]

I think part of the reason we ended up with the current layout, was due to how wider tables were handled by the theme. We could check whether that's still a problem with Furo.

We could have multiple layouts behind different options, to accommodate the needs of different standards.

Thanks Ben, it would be great if we could look at this, and if it looks feasible consider creating a 'wide' table layout option. We're now using the directive in the open referral docs too, and are considering formatting options both in terms of the theme and the layout.

[duncandewhurst]

Are you using furo for new standard docs? I've been looking at the pydata-theme. The top navigation bar helps decrease the menu depth, since you can use it for Primer, Guidance, Reference, and then put second-level navigation on the left (and within-page navigation on the right).

Thanks for the heads-up about pydata-theme! We're experimenting with a lightly customised Furo theme with a view to using it in place of the Read the Docs theme for standards and software projects that don't have a their own theme.

[duncandewhurst]

I just happened across this issue again and it occurred to me that title and description could be combined into one column:

Field	Description	Type	Format	Required
id	Identifier: A universally unique identifier for this network, as defined by RFC 4122. For more information, see the identifier reference.	string	uuid	Required
name	Network name: A name for this network.	string
nodes	Nodes: Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless: The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in .links The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in .links. For more information, see how to format data for publication. See Node	array[Node]

[duncandewhurst]

There's an idea in #48 that might help with layout.