0 Favourites

Tutorial Writing Feedback

  • 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!

  • Construct 3

    Buy Construct 3

    Develop games in your browser. Powerful, performant & highly capable.

    Buy Now Construct 3 users don't see these ads
Jump to:
Active Users
There are 1 visitors browsing this topic (0 users and 1 guests)
Similar Topics Posts Views Last Post
Unread hot topic
410 84,601
MrMegawatts's avatar
MrMegawatts
Unread hot topic
0 Favourites
Tutorial: Platform School
267 93,729
Megabeard's avatar
Megabeard
Unread hot topic
0 Favourites
Examples & Tutorials List
110 211,328
abdalghani's avatar
abdalghani