Alan, this isn’t a hijack at all - it’s a good summary of the underlying issues 
with the different technologies we’re using for authoring documentation.

Straight HTML is compelling because:

- For those who are new to HTML, they can use as little as they feel 
comfortable with and still feel like they are contributing.
- HTML is widely established - lots of good resources to learn from.
- HTML is more understood as “what is seen on the web”. The author knows that 
writing HTML is what will show up on a webpage.
- Authors wishing for more control over their content can use more advanced 
styling and techniques (HTML is robust).

A few well documented Handlebars helpers would be beneficial, especially for 
situations where the HTML structure is a bit trickier. The <figure>  and 
bulleted list situation are perfect examples where a helper could make it 
easier. Also makes it easier to maintain if we ever decided to change the way 
the markup is done.

Aside: the term “Helper” is foreign to someone who isn’t familiar with coding. 
The term “macro” is probably more widely understood and may do better at 
communicating what we mean. Function names and documentation may want to use 
this term instead.

As for the issues with Duplexing with Markdown- I managed to find a more 
general solution that works further down the processing pipeline so there’s no 
funky interactions between HTML and MD. So rather than dealing with the 
problem, it's avoided all together. I guess this speaks to the issue at hand.

- Jon.

Jonathan Hung, Inclusive Designer
OCAD University
Inclusive Design Research Centre

From: Harnum, Alan <><>
Date: October 7, 2016 at 12:14:37 PM
To: Tirloni, Giovanni <><>, Fluid Work 
Subject:  Re: Moving away from Markdown to straight HTML for Inclusive Design 
Guide site

Gio, I think your personal narrative of the process as "the least trained
for these things" is actually a very good example of how we should
approach these design challenges, and a reminder to be wary of what is
colloquially termed the "expert blind spot".

For me, that raises this question: does some of our design problem in
building and evolving a documentation platform perhaps come down to
tensions between the following goals?

1) We want to enable diverse contributions, from a range of perspectives,
experiences and skills.
2) We want to exert considerable control over style and formatting for
purposes of identity and branding.
3) Those of us who are more experienced users of various technologies
involved (non-exclusively: static site generators, template systems,
document markup, style sheets) may prefer to use approaches that make our
lives and work easier through enabling efficiency.
4) Those of us who are newer to some concepts may prefer clarity over

I hope this doesn't feel like a hijacking of the original thread, but
think we may find ourselves in a situation of competing tensions due to
the above, so we should tread carefully and assess possible changes in
light of that.

On 2016-10-07, 8:44 AM, "fluid-work on behalf of Tirloni, Giovanni"
< on behalf of>

>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.., I know some HTML, I know some
>MarkDown, I don't know any handlebars. Add 'figure out what handlebars
>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 ""
>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 ""
>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).
>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
>>/src/documents/activities/> -
>> typical example (Design Guide)
>> Virtuous Cycles
>>/src/documents/insights/> -
>> example with images (Design Guide)
>> Metadata
>>/documents/> -
>> 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
>> <>².
>> 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
>> 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: <>
>> OCAD University
>> Inclusive Design Research Centre
>fluid-work mailing list -
>To unsubscribe, change settings or access archives,

fluid-work mailing list -
To unsubscribe, change settings or access archives,
fluid-work mailing list -
To unsubscribe, change settings or access archives,

Reply via email to