search

openreferral / specification

The Human Services Data Specification - a data exchange format developed by the Open Referral Initiative
https://openreferral.org
Other
117 stars 49 forks source link

Handling long field names in new HSDA docs #178

Closed Bjwebb closed 6 years ago

Bjwebb commented 6 years ago

The table on the HSDA search page, http://docs.openreferral.org/en/include-api-docs/hsda/hsda-search/, currently overspills the page.

image

Bjwebb commented 6 years ago

An alternative is to make the field names wrap:

image

This looks a little bit ugly, but I think if we break on slashes, then it's probably the least bad solution. Thoughts @timgdavies @greggish ?

greggish commented 6 years ago

I defer to @kinlane . Should this issue be in https://github.com/openreferral/api-specification ?

kinlane commented 6 years ago

I would leave this in the UI / doc layer. You wouldn't want spaces injected into spec, but the ui/ doc layer could inject the space safely just for the visual presentation.

Bjwebb commented 6 years ago

Agreed that this is just for visual presentation, I can modify the sphinx directive that generates the table to do this. The directive lives in this repo, hence the issue is here also.

timgdavies commented 6 years ago

@bjwebb I think the suggested modification is the best option for now.

The alternative would be to have two rows for each entry, with the first row with a colspan like we do in OCDS docs. If that's not a lot trickier to implement, then it might be preferable.

Bjwebb commented 6 years ago

Here's what two rows looks like: image

I personally don't like it as much (just in terms of the look, no technical reason), but it's easier to implement, so happy to go with it if you prefer.

greggish commented 6 years ago

Is it possible to indent the description line? Dunno if that will help make it easier to read or maybe worse.

Bjwebb commented 6 years ago

Here's what's easy to do: image

greggish commented 6 years ago

Seems like that's an improvement in readability. I'm fine with it, but i'm not the target user. We could ask for folks to weigh in via slack?

Bjwebb commented 6 years ago

Yes, that could be useful. I don't think I'm on the slack.

timgdavies commented 6 years ago

@greggish If you get feedback views on this issue from Slack that would be great. We can implement updated version first thing in the New Year if there is agreement that the look above is preferred (I quite like it)

greggish commented 6 years ago

No comment in slack. If it works for @kinlane, it wfm

kinlane commented 6 years ago

Thumbs up!

Bjwebb commented 6 years ago

I have a branch and a PR where I've enabled the new layout for all HSDA tables: Preview: http://docs.openreferral.org/en/178-long-fieldnames/hsda/hsda-search/ Pull request: https://github.com/openreferral/specification/pull/186