As a web developer, I spend a lot of time programming websites for people who don’t necessarily know what Markdown is, why they would use it, how they would use it. People who are just “ordinary people” who may not even know what HTML is.
With that said, perhaps a portion of the website should be dedicated to describing in the simplest terms possible how to perform certain actions using markdown - much like forums have for bbcode.
Obviously this should be open source on github or something similar taking pull requests - perhaps translated to multiple languages, too.
I don’t think a tutorial like that is what most users will need when we give them a field where they can write Markdown. It is more an help page than a tutorial (the tutorial can still be useful for people wanting to discover more from Markdown though)
I love your tutorial! If you want to move it (mirror it) under CommonMark.org that’d be great. Note that these are currently all static HTML and JS pages, though.
Has any progress been made on creating a simple user’s guide for CommonMark?
I would like to contribute, but obviously there is no point starting on a new guide if an effort is already in progress.
I like the layout of the Ember.js guides, with separate pages for each of the main features accessible from the lefthand navigation. A similar approach could be taken for Markdown, with each major feature that writers will understand (emphasis, headings, code, links, images, etc) having it’s own page.
The Ember site is a static site using Middleman, and the guides themselves are just Markdown files hosted on GitHub. This is preferable to writing a guide in HTML; if Middleman was used for the site, the source Markdown files for the guides could be kept together with the site in git.
In any case, I think Markdown is the obvious choice to write the guide in. If there are no objections, I can start writing one based on the current spec within the next few days.
I think I found printable reference cards to be most useful for me at least. ( A4 sized, stuck to the wall ). But then again I’m still a paper kind of person.
I think there’s value in a longer guide like this as well as a shorter guide (like the Stack Exchange one). Perhaps a “Quick Reference” page at the beginning with links to the longer pages?
A set of “clickable quick reference cards” that jumps to the full reference’s section. Think of a slideshow, but with a “Expand for full explanation” kind of thing.
If you can keep each card as small as possible, and make each card fluidly responsive layout. Then the page would also double as a printable to sheet of paper (or a couple) reference. (Just remember to remove the “click to expand” link)
I was thinking of something like the Ember guides. For example, if you click on Templates, it expands to show a number of subpages - similarly, you could click “Headers” and it would expand to show “Setext Headers” and “ATX Headers”. It might work as a grid layout instead; we’d need to think about how subsections would work in that case.
By the way, there’s no reason why the print and web layouts need to be the same. You can define a separate stylesheet for print in CSS. One of the nice things about using Markdown (or HTML) to write the guides is that the layout is completely separate from the content. If we create a quick reference guide, we could create separate poster layouts for A4 and A3 pages. But I think web readers should be the primary target audience to start with.
I like the idea of giving people a little “try it out!” input box below the instructions so they can experiment in real time.
I also really like your “things to watch out for” sections, those are hugely important. There are a few things that trip average people up and we should be up front about those.
I’m in the process of preparing a Middleman site for the CommonMark-specific guides that I’m writing. This will allow us to edit the guides in Markdown, with the table of contents pulled from a YAML file. The built site will run on GitHub Pages. I’ll aim to get something up on GitHub tonight.
@gjtorikian I’m happy to work on combining your guides with these new guides and then (once ready) preparing the pull request.
I quite like the idea of a “try it out” input box. Maybe we can autodetect any code blocks in the markdown tutorial via javascript, and assign a “try me button”. This would copy the text to a floating markdown editing windows like in this “discourse based forum”
