Tutorial Writing Feedback

If you have found a bug, or have a suggestion/comment then leave it here

Post » Fri Oct 30, 2015 7:03 am

I just wrote my first tutorial and have some feedback.

Right off the bat I noticed the editor was generating what appeared to be Markdown "code", and was pretty happy because that meant I could easily write and do basic previews in my code editor, while saving a copy just in case (I've learned this lesson the hard way too many times in the past). So that was awesome. However not so awesome was when I learned that if it is indeed Markdown, it's a heavily modified version. There were 3 areas that stuck out negatively for me.

Headings

I definitely get not having additional h1s on the page, but within the editor the h1 button inserts markup for an h2, and then the h2 button actually inserts the markup for an h1, which then later gets rendered as an h3. It felt odd and inconsistent to me. I feel like it would be better if the markup for headings was the same, and then in the custom render you kick everything up a number. That way #Heading 1# gets rendered as an h2, ##Heading 2## gets rendered as an h3, etc. Everything is consistent in the editor, matches regular markdown syntax, but still shows correctly.

There's also some funkiness with h3's. I can enter ###Heading 3### all day long and it renders right in the tutorial and the preview, but the table of contents shows the h3 and a p tag as text.

H4's don't have a renderer. Most tutorials probably don't go that far, but it was surprising when mine did and I got a h3 surronded by #'s.

Code

I would like to suggest using GitHub flavored markdown for code. That allows for using ``` to fence in code blocks, and is sooooo much easier than the 3 or 4 spaces used by default within markdown. My tutorial included a lot of javascript to include on the page and to use as execute javascript actions, so it was kind of a pain, but a pain felt all over with regular markdown.

Page Breaks

This one is less of a pain, but instead of converting a bunch of = into a page break I feel like it would be more intuitive to override markdown's hr renderer, which is 3 or more - or _.


Thanks for the awesome application, and the great community with tutorials and forums, they've been a life saver just starting off with this!
B
7
S
3
Posts: 7
Reputation: 790

Return to Website Issues and Feedback

Who is online

Users browsing this forum: No registered users and 0 guests