Table formatting in the schedules section

[dan-odsc]

Table formatting in schedules section needs to be looked at.

Been through all of the docs and this is the only instance. The other one we found and fixed was in the Logical model section but this has been sorted.

[mrshll1001]

I've investigated this and I think the tables are simply too large. I investigated by injecting/removing various css classes on the rendered page, as well as recreating the issue by writing a new table incrementally. After a certain size / number of columns, it simply breaks out of the container.

Given that there many more columns than rows, it may be more appropriate to simply transpose the tables; this may support readability anyway.

This would mean going from this (truncated):

id	service_id	valid_from	valid_to
1098	35	2020-04-01	2020-12-20
1099	35	2020-04-01	2020-12-20

to this (also truncated):

field	/0	/1
id	1098	1099
service_id	35	35
valid_from	2020-04-01	2020-04-01
valid_to	2020-12-20	2020-12-20

The header row can be labelled appropriately. I've used array notation but we can be explicit and say e.g. Entry 1 or something.

On top of this, I would also like to move away from hardcoding tables for worked examples in rst and markdown. We can do this by using the csvtable directive, which takes a csv file and renders it in the docs where we tell it. This separates out the concerns of maintaining the page flow and the worked examples, making it easier to add/update worked examples consistently, and prevents errors from people writing rst tables (I found an error already, causing the schedules tables to render with some cells spanning two columns). It also allows people not as comfortable with markdown or rst to participate in producing examples since they can use spreadsheet software to create the files.

I propose creating a subfolder of docs/hsds called worked-examples which contains these csv files. The first action would be to migrate the (transposed) tables on the schedules page and adjust accordingly. I can then scope other worked examples and migrate them.

@dan-odsc @kindly @Bjwebb @greggish are there any concerns with this approach? If not, I can start on this soon.

[mrshll1001]

I've had some additional time to think about this and have the following thoughts:

• We should discuss separating out examples into their own folder — and then importing them into the docs pages dynamically — in a separate thread. I've opened #441 to do this.
• @Bjwebb raised the point that transposing tables like this means that, technically speaking, the listed example wouldn't validate as HSDS data if copied and pasted and ran through our tools. While potentially fine, we should strive to keep our examples as close to reality/valid data as possible.
• Related to the above, while examples provided in tables is good and clear; we should consider providing examples as JSON where possible as well. HSDS is a JSON standard now, so we can take the opportunity to illustrate this. We might be able to bundle the HTML table example and a corresponding JSON example together via a similar process we use for the objects and fields on the Schema Reference page (ie having them in tabs)

Keen to hear from others if they've got thoughts.

[dan-odsc]

Thanks for this @mrshll1001,

@greggish Just bringing this to your attention.

Dan

[greggish]

I'd like to hear what folks in the dev community think. Should we post in the forum? Not sure if this thread is the right one for it, or a new one. cc @Cskyleryoung @devinbalkind

[devinbalkind]

For wide tables, can we adopt a horizontal scroll? https://knowyourtoolset.com/2018/02/controlling-the-width-of-a-table-with-read-the-docs/

I agree about the points related to JSON. We should use it more seeing as we're a JSON standard now.