Create a page or subdomain for a simple user's guide!

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.

2 Likes

This is a great idea – if someone can provide HTML in a pull request, I am happy to bring it in!

https://github.com/coding-horror/coding-horror.github.io/

What should the URL for this help be? help.commonmark.org? Or a subfolder? Or the homepage itself?

For reference, here is the GitHub guide about using Markdown: https://guides.github.com/features/mastering-markdown/
It is linked from most (all?) places in GitHub allowing to use Markdown.

This looks similar to the idea suggested here

I built markdowntutorial.com to surprising popularity. I’m happy to create something similar here–or just have this site link out to that.

2 Likes

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.

And @stof I was thinking we could have both.

@codinghorror the tutorial is at https://github.com/gjtorikian/markdowntutorial.com It is a Jekyll website, so static as well

1 Like

I think the tutorial would work great as a try.standardmarkdown.com, kind of like try.github.com.

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.

1 Like

That would be great! Feel free to look at the work we did at Stack on this, too, if it has any useful ideas

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’ve not made much progress so far, but here’s an early, work-in-progress version so that you can see the format:

https://github.com/chrisalley/commonmark-guides/wiki

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?

Well, the way I would do this:

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.

1 Like

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.

Good point.

The issue I have with Ember guides, is the number of clicking I need to do if I’m just a beginner.

Hence I prefer something like a page that looks like a quick github markdown guide, but has an expand button under each concept it is trying to teach.

Basically just use http://www.w3schools.com/tags/tryit.asp?filename=tryhtml5_summary . No need to make it too complicated or fancy. It’s a bloody simple user guide :smiley:

<details>
  <summary>
   Quick Explanation of markdown concept
  </summary>
   <b>More detailed explanation for those who need it. <b>
</details>

e.g.

Quick Explanation of markdown concept (click to expand) More detailed explanation for those who need it.

With the details tag, you could have a javascript button on top that auto expands all the information and hides the summary.


That’s not to say that a site nav sidebar isn’t useful, but it’s not very good for “casual browsing” with the scrollwheel. Ideally you have both.

@chrisalley can you fold in the work from @gjtorikian ?

http://markdowntutorial.com/

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.

Hah! Not sure how I missed this topic @codinghorror …from two months ago.

No worries about static files; GitHub - gjtorikian/markdowntutorial.com: Lessons to help guide new writers into Markdown! runs on GitHub Pages, so it’s already just a set of static content. Looks like the CommonMark site is also just on Pages. Should I just make a PR to move everything over? I can turn the domain into a redirect to the CommonMark site.

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”