David's decoratePage() notes / Authoring Best Practices

[davidnuescheler]

Overview

I started creating a pattern for helix-page implementations where I use a decoratePage() function that adjusts the DOM to a way that makes it intuitive to style and use for other javascript purposes. the decoratePage() is should be called as early as possible (at on DOMContentLoaded).

This allows us to isolate all the initial DOM manipulation in one place and get an overview over common patterns that we should consider to handle in a certain way and eventually consider to move to the server either as a fixed part of helix, helix-pages or provide an extension point that makes this easily possible.

At this point there is no need to action, but I just wanted to have a place to write things down, and I didn't know where that was so I picked this place.

1. The section background color quandary

I found that most pages have sections with different backgrounds, and at the same time see an example here:
https://staging--pages--adobe.hlx.page/xd/en/xd-cloud-file-launch

The main issue is that our default markup...

<main>
<div class="default">
...
</div>
<div class="default">
...
</div>
<div class="default">
...
</div>
</main>

does not offer up an easy style to deal with this very commons situation, which leads me to to almost by default wrap every main>div with another "outer" div almost by default.
I may very well be missing a css trick to achieve this very common layout in a reasonable way without having nested <div>s, but i think the expectation from a frontend dev would be to have two divs.

2. Section attributes in word or gdoc using tables

in markdown we are using frontmatter to allow for injection of class attributes on the section <div>, which is extremely helpful. unfortunately we haven't found anything equivalent for word or google docs that's intuitive to author.
After this being a vexing problem and going the route of using headings (either through their id, first word, or even heading size) as a trigger to attribute styling, or to secondarily to leverage links to identify sections that need to be treated in a special way, or even to include hidden <code> sections that the author would place in those sections, i noticed that none of these options are really viable either because they make the doc ugly and hard to read or introducing too much magic, that continuously needs css changes as a website grows.
Then I discovered that most ergonomic and intuitive authoring experience comes from (ab-) using a table with two rows and one column. it provides a nice visual frame and allows to place attributes (in a human readable way) into the column head.

Lists as tables in word and gdoc

It turns out that lists have a range of formatting and nesting limitations and require very careful editing to not confuse paragraphs and line-break. So it turns out that a lot concepts that would intuitively be lists in both markdown and html are more much more easily edited in tables.
It turns out that tables also offer at least one more level of intuitive grouping and separation between elements through columns as well as offering a means to leave some layout / typing hints through the column headers.
The biggest issue here is that markdown seems to have quite and expressive way to deal with lists while that's really not ergonomic (or impossible) to edit in google docs and word, and conversely markdown really only has a very simplistic table model while google docs and word are extremely robust authoring and fidelity in tables and table cells.
As an example see the contrasting two styles of potentially authoring cards of this page...
https://pages.adobe.com/premiere/en/yts-livestream

[trieloff]

1. our declarative markup should be able to handle that – @ramboz
   2 & 3. maybe we can introduce a de-tabelizer that takes all tables that are not pure data tables (e.g. have a line break in a cell) and transform them into something more palpable.

[tripodsan]

1. 2 & 3. maybe we can introduce a de-tabelizer that takes all tables that are not pure data tables (e.g. have a line break in a cell) and transform them into something more palpable.

this can get very difficult, since there is no real row separator. imaging nested tables, etc.
I suggest to use a more robust table format if needed, like: https://pandoc.org/MANUAL.html#extension-grid_tables
the drawback would be, that it isn't default markdown anymore and that we need to implement the parser.

[trieloff]

The way I see it, David is using tables in Google to express something that would not be a table in sane Markdown. Instead it would be a section (2) or a nested list (3).

If we decide to make the conversion at the word2me level, then we don't have to extend the table format. If we want the conversion to happen in helix-pages, then we do.

[patelpk]

I'm late in the discussion here (and i have not read the other 142 authoring best practices that i assume come before 143) but if you use a table as a representation for a section, what about when a table is actually a table? At some point, a word document in its own format used to produce a word document can't match 100% an authoring template that will be transcoded into another markup without some special formatting rules the user will have to learn. I see it similar to what DITA was used for. Is the end purpose to not introduce or require ANY formatting controls in the content document? People use DITA and word as a way to create complex documents that can have both formatting/transcoding rules as well as variables for replacement at delivery time. {user name here} or {{inherit style from parent}} so it's a combination where people that know how to do these overrides can use them but it's not necessary for simpler content. it's known and was starting to be used by AEM with the DITA add-on in a few places i have seen. Even in basic usage of word this is done to have a word 'template' which allows for the mail merge feature to create multiple versions of a document. Just like CSS these elements could have a 'dictionary' within an organization so commonly used items are not repeated {{header}} so people can work on 'portions' of a document and not have to create a 'whole' page. Again, ignore these if previous threads have discussed this already as i read more regarding this project.

[trieloff]

if you use a table as a representation for a section, what about when a table is actually a table?

A table that represents a table should stay a table. A table that represents something else should become that something.

If a table has only one column, it's barely a table and could stand for a section.

If a table has values that contain line breaks and paragraphs (something that Markdown doesn't know) it could stand for a segmented list.