Deprecations Appendix is seriously ugly

[hcayless]

I mean, just look at it: http://www.tei-c.org/release/doc/tei-p5-doc/en/html/DEPRECATIONS.html. Is that a table? I can't even.

[martindholmes]

Syd and I had that looking lovely when we first did it. Something must have changed. The date column should be centred. We could add table borders if that helps too.

I think it depends how much stuff happens to be in there; when there are lots of rows and content, the table organizes itself a bit better.

[jamescummings]

Why have it be a table at all? Why not just a list with a few nested items per deprecation item?

[lb42]

It looks a mess because there is already so much visual clutter on the page. But if you want to make it less of a mess:

• lose the redundant subheading ("appendix G.1")
• add some background fill to the heading row
• add some whitespace at left and right of the whole table
• left justify the column headings
  The last three are trivial tweaks to the CSS.

I agree with James that it doesn't need to be a table when there are so few items, but given that it probably does when there are many, and given that you don't want to have to revisit this problem every time you do a release, it's probably worth spending a bit more time on formatting the table acceptably.

You could also perhaps add some more explanatory text about what exactly is meant by deprecation at the beginning.

[jamescummings]

To be clear, the reason I think it would be better as a list rather than as a table isn't to do with the number of items being deprecated but the nature of the data in the table. It is because after the thing-being-deprecated there are only 3 columns, one of which is a substantial prose column 'Description'. While the two examples given at the moment are fine with a quite terse description, I can certainly picture possible deprecations where a more substantial paragraph of prose is needed to explain the reason for the deprecation and workarounds or modifications needed by those who are affected by it.

I'm not sure if I can turn that into a generalised rule but whenever one's table has substantial prose in it, I think is probably worth looking at expressing it another way. I don't want to sort the data in this table (other than by its deprecation date which it already is) so that makes me more convinced it shouldn't be a table.

Plus, given the non-responsivity of the TEI Guidelines HTML output, it looks crap on my mobile phone. ;-)

[martindholmes]

For whoever goes in to fix this, @sydb and I documented exactly how it works in a section in TCW20 called "Adding or Editing an Appendix":

http://teic.github.io/TCW/tcw20.html

[sydb]

@jamescummings: that description is just the content of the appropriate <desc> pulled in. Yes, @martindholmes is right, it looked better when we had a lot of stuff. But I think @lb42 is right, some CSS tweaking is in order. (And I’m not very good at that sort of stuff.)

[martindholmes]

I added a bigger margin below the table, and centred the date column. Do we also want table and cell borders?

[martindholmes]

Does this look slightly better?

https://jenkins.tei-c.org/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/doc/tei-p5-doc/en/html/DEPRECATIONS.html

[hcayless]

I will try to explain what I hate about each column.

1. I don't know what the identifier gives me, other than a link to the spec where the deprecation resides. The link itself is good. The text of the link adds nothing useful. Maybe just give the context (e.g. teidata.point or content)? And then make the column header "Context".
2. I don't know what column two adds. Suggest getting rid of it.
3. The header is massive. Change to "Removal After" or something like that.
4. Column 4 is fine :-). It does occur to me that we don't really flag deprecation-related schematron rules on the spec page, and maybe we should. This description just appears over the rule, unmarked.

[lb42]

And there is still a redundan t sectipn sub headibf! reluctantly using Outlook for Android<https://aka.ms/ghei36>

…

________________________________ From: Hugh A. Cayless <notifications@github.com> Sent: Monday, February 4, 2019 6:09:40 PM To: TEIC/TEI Cc: Lou Burnard; Mention Subject: Re: [TEIC/TEI] Deprecations Appendix is seriously ugly (#1854) I will try to explain what I hate about each column. 1. I don't know what the identifier gives me, other than a link to the spec where the deprecation resides. The link itself is good. The text of the link adds nothing useful. Maybe just give the context (e.g. teidata.point or content)? And then make the column header "Context". 2. I don't know what column two adds. Suggest getting rid of it. 3. The header is massive. Change to "Removal After" or something like that. 4. Column 4 is fine :-). It does occur to me that we don't really flag deprecation-related schematron rules on the spec page, and maybe we should. This description just appears over the rule, unmarked. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#1854 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AAoU9G-525z7d0p-gAEex43z_rNiOR_bks5vKHdkgaJpZM4afDyJ>.

[martindholmes]

I think we were just trying to put in all the information we ourselves would want to see in any release of the Guidelines, in order to check whether anything we rely on was deprecated. All the info in the table seems useful to me, but I guess if it looks ugly, it can easily be removed. Why not re-jig it to look the way you'd like it to, and see if everyone agrees?

[emylonas]

cell borders would make it a bit easier to read. column 1 - clearer to give name of context (agreeing with HC above) column 2 - could be made clearer by a better heading. What other possible values could it have? Column 3 - header is verbose so basically repeating comments from above. another vote.

…

On Mon, Feb 4, 2019 at 1:40 PM Martin Holmes ***@***.***> wrote: I think we were just trying to put in all the information we ourselves would want to see in any release of the Guidelines, in order to check whether anything we rely on was deprecated. All the info in the table seems useful to me, but I guess if it looks ugly, it can easily be removed. Why not re-jig it to look the way you'd like it to, and see if everyone agrees? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1854 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABwP5RGtxREQVsRI5Lo3kb46qE5yuSzLks5vKH6tgaJpZM4afDyJ> .

[hcayless]

I've had a go at reformatting the deprecations appendix as a list. If there are screams of rage and disappointment, this change can be rolled back. If not, I will close the issue.

I agree with @lb42 about the redundancy of the subheading, which is a side effect of the div structure of the appendix. If it's reformatted as a single div rather than a nested div, then you get the navigation TOC thingy on the right instead of the left and it looks weird (not least because the header assumes it's there and is positioned to be out of its way). There's a larger Guidelines redesign issue lurking here, but in this case, I think we have to live with it for now. We could make it less stupid simply by adding a section at the top with our deprecation policy in it...

[jamescummings]

@hcayless Maybe make items bulleted?
And maybe make the dates bold?

[martindholmes]

FYI you can format a table as a list using pure CSS. We do that with large tables such as this:

https://mapoflondon.uvic.ca/mdtPrimarySourceLibraryProclamation.htm

If you make your browser window big, it's a table; if small, it's a list.

[hcayless]

@jamescummings how about now? I'm not sure the bullets add much, tbh, but it's fine.

[martindholmes]

I find this less readable than the table, to be honest. At least with the table you know where to find each piece of info (deprecation date or whatever) in its column.

[martinascholger]

What about a table with two columns, date and description?

Date	Description
2022-02-15	The use of value inside charProp to specify a character or glyph property value is being replaced by either unicodeProp, localProp, or unihanProp.

Or, a list with the date at the beginning.

• 2022-02-15: The use of value inside charProp to specify a character or glyph property value is being replaced by either unicodeProp, localProp, or unihanProp.

[hcayless]

We may tweak this further, but it's not as messy as it was, so closing.