Description
Just a brain dump of pain points and feature requests for tutorial creation.
Parser Error Feedback
It would be super helpful if the parser could tell you exactly where something unexpected happened and what should be there in its place. Down to the line number. Even better, lint the markdown in near real time for quick feedback.
Hard to Visualize
It’s hard to visualize and write markdown content without an editor.
Updating Commit Hashes after Rebasing
Every time I rebase to create a new version of the tutorial code (which is often), I have to manually go over the git history and update all subsequent commits in the tutorial. This is super painful. In Meteor-Tutorial-Tools they got around this by enforcing commit names, like “must start with 1.1”.
Validate Tutorial Commits
Tutorial commits should:
- exist on the branch
- be in the correct order
Currently, it's very easy to make a typo and break a tutorial, as commit hashes are strange and entered manually.
Separating tutorial runner setup commits from code commits
In order to ensure the test runner is setup before starting, I've added a section where the testRunner commits can be added. It's a bit messy, and I wonder if there is a better solution.
Hard to Debug Tutorial due to Random Level/Step Ids
I’m trying to debug issues with progress/position in the tutorial, but it’s not clear from the ids were in the tutorial I am. It would be easier if these had ids like “1.1” or “1.2”, etc.
Confusion on what goes where
The current script requires a knowledge of where things go “config first, content second, etc”. This is especially hard for new tutorial creators. It’s also more difficult to validate or give feedback in markdown, whereas with YAML or JSON there are clear keys that say what is what, like “title”, “content”, etc.
JSON schema, for example, allows you to provide a validation of values for each key, along with a description of what should be there and a suggested example.
Ideally, it would be great if we could have people enter information in a kind of controlled form.
Matching App Versions
Tutorials have a format that matches up to what the extension version is expecting. I have a bit of code that allows you to specify an app version range for a tutorial, but wonder if this could be simplified further?
Supporting New Features
How do we add new features like:
- Hints? An array of markdown strings that provide the user clues
- Points? A basic reward system
Easily Editable
In the spirit of open-source, it would be great if tutorials were easily editable by not just tutorial creators but users as well. Eg. editable from GitHub
Validating Tutorials
When rebasing a tutorial, it's possible to break something on the way. I'd love to have a build tool that would:
- at a minimum, run tests from the final step to validate they work
- git checkout each solution step and run the tests on it to ensure they work
Tutorial Feedback
It would be cool if there were an easy way to provide feedback on a tutorial from users
Private Tutorials
It would be amazing if we had a way to make the solutions private - or especially make the entire upcoming git log inaccessible.
Rebasing
Tutorial creators are often not very familiar with interactive rebasing - which is kind of necessary for versioning and adding changes to a tutorial. Is there a way to simplify this?
View Tutorial Content as if in Extension
It would be super helpful to see the tutorial content as if you were in the editor itself. This is because markdown doesn't always come out the way you expect. There are even cases where validating code blocks come causes the app to not load if the language of the code block is not supported.
Tutorial ID
How to generate a unique tutorial id? Eg. user/name? Eg. coderoad/fcc-learn-npm from the repo uri?