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

Wed Oct 12 12:29:28 UTC 2016

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
Email: jhung at ocadu.ca<mailto:jhung at ocadu.ca>
OCAD University
Inclusive Design Research Centre

From: Harnum, Alan <aharnum at ocadu.ca><mailto:aharnum at ocadu.ca>
Date: October 7, 2016 at 12:14:37 PM
To: Tirloni, Giovanni <gtirloni at ocadu.ca><mailto:gtirloni at ocadu.ca>, Fluid Work <fluid-work at fluidproject.org><mailto:fluid-work at fluidproject.org>
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
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

_______________________________________________________
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20161012/ae1e88b8/attachment.htm>