Moving away from Markdown to straight HTML for Inclusive Design Guide site

[Tirloni, Giovanni]

At the risk of making a fool of myself here because I'm the least 
trained for these things, let me share my thoughts while going through 
the guide and checking some of the source code.


1. Click on "Edit this on GitHub"

Thoughts: "Hmm.. index.html.md.handlebars, I know some HTML, I know some 
MarkDown, I don't know any handlebars. Add 'figure out what handlebars is'"

2. Reading the index file

Thoughts: "I don't know where getCategoryIcon comes from but it must be 
that handlebars thing. I need to keep track of where I'm reading HTML 
(focus on the <div>'s, ok...), then handlebars is probably between '{{{ 
}}}'... is line 31 Markdown?

3. Reading "VirtuousCycles.html.md.handlebars"

Thoughts: "Markdown is saving me the need to type <p></p> about 4x and 
<h2> once. This handlebars thing seems pretty simple now.. 
getCategoryIcon inside brackets... but it looks like there's MarkDown 
inside that <li></li>??"

4. Reading "InclusiveDesignMapping.html.md.handlebars"

Thoughts: "What's HTML figure? <google>. Ok, fine. I see Markdown inside 
HTML again. Markdown saves me from writing <h2></h2> six times and 
<a></a> a dozen or so times... It's more readable but I do get to read 
HTML, Markdown and handlebars all in a single line. I hope I open/close 
those brackets right".


The cognitive load causes some anxiety because I don't know when I will 
hit the corner cases (like you seem to have).

If I had any knowledge to share about inclusive design, I would 
certainly be spending some time catching up on HTML, Markdown and 
handlebars... at which point I may have no energy left to share whatever 
it was I wanted to share.

A personal anecdote: unfortunately this is exactly what happens a LOT 
while working with sysadmin/DevOps tools: you spent so much time going 
down the rabbit hole that after a few hours you forget what was your 
goal in the first place. Sometimes you can keep trying to make 5-10 
tools work together and you keep hitting corner cases everywhere. Maybe 
this made me more 'sensitive' when I see something like this. 
Unfortunately, for sysadmin/DevOps tasks, there is no escape, it is what 
it is since the dawn of time.

TL;DR; I think HTML (and some handlebars I don't have to learn about) 
would be simpler (certainly not beautiful to read).

Giovanni


On 10/05/2016 02:33 PM, Hung, Jonathan wrote:
> Hi everyone,
>
> For the Inclusive Design Guide site we have been using a combination of
> both markdown and native HTML in the source document files.
>
> Examples of mixed HTML and Markdown:
>
> Cause and Effect
> <https://github.com/inclusive-design/guide.inclusivedesign.ca/blob/master/src/documents/activities/CauseAndEffect.html.md.handlebars> -
> typical example (Design Guide)
> Virtuous Cycles
> <https://github.com/inclusive-design/guide.inclusivedesign.ca/blob/master/src/documents/insights/VirtuousCycles.html.md.handlebars> -
> example with images (Design Guide)
> Metadata
> <https://github.com/fluid-project/docs-inclusive-learning/blob/master/src/documents/Metadata.html.md.handlebars> -
> also in the Inclusive Learning Design Handbook and elsewhere (ILDH)
>
> The main motivation for using Markdown was to make it easy for
> contributors to author content without having to know HTML. However,
> because of our styling and formatting requirements, we have both HTML
> and Markdown in the same files. Thus requiring the author to use both
> formats in a document.
>
> To complicate matters for authors of all skill levels, Markdown is very
> particular how you mix HTML - nesting Markdown inside a block level HTML
> element causes it not to render properly as described by Point #3 of
> this article “Three Markdown Gotchas
> <https://blog.stackoverflow.com/2008/06/three-markdown-gotcha/>”.
>
> Given our increasing need to control style and formatting in our
> documentation, I wonder if it would be beneficial to switch to straight
> HTML within documentation source files for the Inclusive Design Guides site?
>
> Transitioning to straight HTML would also make the task of creating
> print-ready duplexed layouts easier as we would be able to use block
> level containers and not worry about the content not rendering.
>
> Any thoughts?
>
> - Jon.
>
>
> ---
> Jonathan Hung, Inclusive Designer
> Email: jhung at ocadu.ca <mailto:jhung at ocadu.ca>
> OCAD University
> Inclusive Design Research Centre
>