Problem/Motivation

After finishing translation of that file, I'd bet that 2.3. Concept: Content Entities and Fields topic is definitely amongst the most difficult ones to explain clearly. Thus its large comparison table does a vital job in trying to help get through the matter to the Reader. We need the content of all the five columns for sure.

My observation is that the last column (called "Examples") contains a much bigger volume of text than the other four. That causes huge white areas on the left and a narrow, hard-to-read text on the right. That kind of visual frustration could have a bad effect on focusing to the topic holding back the Reader from having a better understanding on such a key important subject.

Proposed resolution

I tinkered around a bit with awesomly flexible AsciiDoc syntax and reached the following results depicted on the right half:
Comparison of before and after.

Although the situation is not that bad with English:
Comparison of before and after.
Anyway, I provide a patch to let others try out my suggestions on their own.

CommentFileSizeAuthor
#2 2874565-better-table-structure-for-planning-data-types-2.patch3.62 KBBalu Ertl
#2 better-table-structure-for-planning-data-types_en.png82.83 KBBalu Ertl
better-table-structure-for-planning-data-types_hu.png87.36 KBBalu Ertl
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Balu Ertl created an issue. See original summary.

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented
Issue summary: View changes
FileSize
better-table-structure-for-planning-data-types_en.png82.83 KB
2874565-better-table-structure-for-planning-data-types-2.patch3.62 KB
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Assigned: Unassigned » eojthebrave
Status: Active » Needs review
Issue tags: +Translation updates needed

I like it! Thanks for the issue and patch.

Any thoughts Joe?

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

Looks like a good idea to me. +1

Thanks for the suggestion @Balu Ertl

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I have a question about the patch. Why are there so many {nbsp} lines in the patch(es)? Are they necessary for the table formatting? They seem a bit odd, especially the one at the end of the table. Can they be removed?

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented

I put them to make some extra room between rows for easier overview. I admit it's not the most elegant solution, but I had no better idea at the moment. I learned this trick from here: https://github.com/asciidoctor/asciidoctor/wiki/How-to-insert-sequential...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I'm not excited about them either, and I think they will cause confusion and/or errors for future editors and translators. Does it look terrible without them?

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented

Actually not that bad without them neither, so feel free to remove them.

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented

I'm Glad to hear that both Jennifer & Joe agrees, do you think shall I commit our HU file with this table structure, so we can see how it works for displaying on Docs and generating ePub/PDF output?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Please feel free to commit to the HU version. :) For the EN version, let's have a new patch without the nbsps in there and go forward.

I have not tested this will build correctly and what it looks like in the e-book versions, but will do that later... I am traveling for the next 2 weeks without a laptop so I cannot do it until I get back. (Having a nice vacation in Costa Rica!!)

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented

Alright, so I committed in with the extra new lines, let's see, how it will look like:
http://cgit.drupalcode.org/user_guide/plain/source/hu/planning-data-type...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Fixed

I'm back from my trip... Committed the above patch to the English version, with the following changes:
- Took out the nbsp lines
- Took out the |||| line, which had left a blank line at the top of the table, which looked very odd to me.

Result now builds well and output looks good. Marking Fixed. I will also send out notification to translation groups as per our policy on #2871873: Change process for notifying translation groups about source changes

  • jhodgdon committed ff1da88 on 8.x-2.x 
    Issue #2874565 by Balu Ertl, jhodgdon: Better table structure for...
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Here's a link to the notification message I sent, for reference:
https://groups.google.com/forum/#!topic/d8manual/Jrs0F8XInPw

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented

"Result now builds well and output looks good."

@Jennifer, does it mean that there's a new deploy to Docs pages or a new ePub/PDF release shining somewhere on the horizon?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Good idea, I will see about a new release and a deploy to docs pages next week.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

The new ebook release is out!

New deploy to drupal.org is in progress... should be there later today I think.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

https://www.drupal.org/docs/user_guide/en/planning-data-types.html
https://www.drupal.org/hu/docs/user_guide/hu/planning-data-types.html
The build is still in progress, so other languages will be updated in a while...

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented

Ah, snap! Now I realised I was misled by Atom editor's AsciiDoc preview module, which has an even-odd colouring style for table rows, and I did not think through that there's another CSS formatting on D.org Docs. That's the reason of the un-necessary extra row under table head. I will remove from our source file as well.

By the way, with this release HU team has reached the 50% of translation being done :)

  • Balu Ertl committed dd760a3 on 8.x-2.x 
    Issue #2874565 by Balu Ertl, jhodgdon, eojthebrave: Better table...
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Congratulations on the translation milestone!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.