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

[Harnum, Alan]

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
efficiency.

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"
<fluid-work-bounces at lists.idrc.ocad.ca on behalf of gtirloni at ocadu.ca>
wrote:

>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
>>
>_______________________________________________________
>fluid-work mailing list - fluid-work at lists.idrc.ocad.ca
>To unsubscribe, change settings or access archives,
>see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work