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

Thu Oct 6 18:48:39 UTC 2016

Hi All,

I can contribute my experience of being a fairly new user of both Markdown and HTML. When I started working on the Guide, I had some experience with HTML, and very little with Markdown. I found that I was having to learn both as we went along for the reasons Jon pointed out - that there seemed to be many things we couldn’t do with Markdown, so we ended up mixing the two. Sometimes I would know how to do something in HTML but had to look up the Markdown syntax.

Based on the email thread here it sounds like there are things we can do to “fix” this or to at least allow us to do more with Markdown (Helpers etc). But if I consider the following two points:

The main motivation for using Markdown was to make it easy for contributors to author content without having to know HTML.

  *   I am uncertain how much friendlier Markdown is vs. HTML to someone who is unfamiliar with the concept of document markup, but I think we also need to recognize that going to pure HTML may represent a step backwards in user friendliness and being welcoming to the non-technical. Do we need some consideration of whether our "styling and formatting requirements" themselves may form a barrier to contribution?

My first inclination would be to say keep it user friendly! But at the same time I personally don’t find Markdown necessarily easier to learn or use than HTML (though my Markdown experience is limited, and this is definitely an over-simplification, but I think “h2” is more intuitive than “##”). I’m sure there are other issues around Markup that I haven’t considered here, like general readability of the doc etc.

More importantly though, if we start introducing Helpers/functions etc, won’t this make the experience that much less user-friendly anyway? In other words, will it still hold that the markdown experience will be more “user-friendly” than HTML?

It’s a bit of an aside, but something I can’t shake is the question of adding complexity in this way making it more difficult to comprehend how things are working (this has been my experience as someone coming onboard and beginning to contribute). We had a brief discussion in the channel about this here: https://botbot.me/freenode/fluid-design/2016-10-06/?msg=74323733&page=1

Hope this is constructive and helpful!

Dana

Dana Ayotte
Inclusive Designer
Inclusive Design Research Centre
OCAD University
www.idrc.ocad.ca<http://www.idrc.ocad.ca/>
www.ocadu.ca<http://www.ocadu.ca/>

On Oct 5, 2016, at 12:03 PM, Harnum, Alan <aharnum at ocadu.ca<mailto:aharnum at ocadu.ca>> wrote:

Hi Jon,

Thanks for getting this discussion started - I make extensive use of Markdown in other areas and find it to be advantageous when I am able to write in "pure" Markdown – for me it's an elegant means of composing longer texts to output to HTML. So prefix the below by saying I'm a big Markdown fan.

My opinions (which don't have a definite conclusion one way or the other):

  *   Tautological statement: the harder it is to author documentation, the less documentation will get written by anyone. It's important that our systems and standards for contributing documentation be as frictionless as possible. I've personally found the requirement of mixing Markdown and HTML to meet our styling and formatting requirements (in both the ILDH and the Infusion Documentation site) to be more onerous than simply using one or the other. I obviously say that as someone who can author documents in both formats.
  *   I think we need to fall to one side or the other of it being possible to create our documentation source code in pure Markdown, or our styling & formatting requirements being complex enough that Markdown can't handle them and we need to expect contributors to author content in HTML
  *   I am uncertain how much friendlier Markdown is vs. HTML to someone who is unfamiliar with the concept of document markup, but I think we also need to recognize that going to pure HTML may represent a step backwards in user friendliness and being welcoming to the non-technical. Do we need some consideration of whether our "styling and formatting requirements" themselves may form a barrier to contribution?
  *   It may be worth looking at the issue at https://github.com/chjj/marked/issues/556 & its linked issues – it's possible we may be able to use the plugin configuration options to get a Markdown parser that behaves more as we would like it.

ALAN HARNUM
SENIOR INCLUSIVE DEVELOPER
INCLUSIVE DESIGN RESEARCH CENTRE, OCAD UNIVERSITY

E aharnum at ocadu.ca<mailto://aharnum@ocadu.ca>

OCAD UNIVERSITY
100 McCaul Street, Toronto, Canada, M5T 1W1
www.ocadu.ca<http://ocadu.ca/>

From: fluid-work <fluid-work-bounces at lists.idrc.ocad.ca<mailto:fluid-work-bounces at lists.idrc.ocad.ca>> on behalf of "Hung, Jonathan" <jhung at ocadu.ca<mailto:jhung at ocadu.ca>>
Date: Wednesday, October 5, 2016 at 1:33 PM
To: Fluid Work <fluid-work at fluidproject.org<mailto:fluid-work at fluidproject.org>>
Subject: Moving away from Markdown to straight HTML for Inclusive Design Guide site

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<mailto: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/20161006/2d0cb1bb/attachment.htm>