treehouses / treehouses.github.io

A Markdown Wiki for treehouses 🏡
http://treehouses.io
132 stars 107 forks source link

Revise Resources on Step 3 (Markdown and Fork Tutorial) #807

Open JLKwong opened 3 years ago

JLKwong commented 3 years ago

Problem

Some instructions in Step 3 are unclear or contain overwhelming amounts of information, which would deter new interns.

  1. "Preparation" is unclear in what one is supposed to do, but this might be caused by issue #2 (having several pages of links and thousands of words).

  2. Unlike the Markdown and MDwiki links, the GitHub link is extremely verbose, with several pages of links and thousands of words, and it's unclear which sections the intended reading is supposed to include, when the reading is supposed to stop, or what sections should be skimmed. It's also not clear that this is for reading only.

  3. 5 resources for learning Markdown syntax can cause decision paralysis, and some prospective interns may waste time doing all of them 'just in case' despite the note.

    Steps to reproduce the problem

    N/A

    Screenshots

    image image

    Proposed solution

  4. Delete Preparation, AND add Readings

  5. Replace GitHub's hyperlink with a link to a more concise summary/reading for GitHub, much like the ones for Markdown and MDwiki. I'm not sure what the original intended learning for this link was supposed to be, and I am not experienced enough with GitHub to recommend resources.

  6. Move the top 3 resources down at the bottom, AND create a new section of these Markdown resources called Additional Resources for Markdown, explaining that these are optional resources that the user might find useful. I left the other 2 resources because they are interactive (active learning promotes long-term learning, especially for syntax).

BryanGazali commented 3 years ago

We'll approve this issue, but it does seem like a fairly extensive solution to complete. We'll let you try to do this but if this ends up being too hard to complete and you want to move onto something else, that's ok.