Tutorial Issue: Referencing by line number only "breaks" the tutorial itself

RESOLVED WONTFIX

Status

defect
RESOLVED WONTFIX
6 years ago
6 years ago

People

(Reporter: Arty-chan, Unassigned)

Tracking

Details

(URL)

(Reporter)

Description

6 years ago
As I was writing a tutorial, noticed an important issue.

Right now, you can only refer to a line number, but as the tutorial goes on, the user will be adding/changing/removing code from the project. So when working on the next section, the line numbers will be wrong.

As an example, you can 'remix' the project (see link) that I started.

In section 2, I ask someone to add a list item.
In section 3, I refer to a blockquote on line 22, but since the user added a list item in the previous section, this is now line 13.

I could try to predict which line it will be if the user follows my tutorial exactly as instructed, but we all know users don't always do that.

In order for the tutorial to actually work, creators must be able to refer to specific lines or sections another way.

ID or class might do it, or getting creators to add unique references which would then be picked up by tutorial.js would work too.

Comment 1

6 years ago
we might be able to do this by adding "automagical" CSS selector resolution, although keeping it readable is going to be interesting. Telling people to go to "line 2" makes sense, telling them to go to "#demosection .initial button.base" might not be as easy to parse for human eyes.

Comment 2

6 years ago
possible way to solve this: a <span> with data-target="selector text goes here", and the actual "what humans read" text as span content.
@Arty, within a session, the line references should update as the user edits the code. In your example, when you add a list item, the tutorial (all of the steps) should now refer to the blockquote as line 23. Can you confirm whether seeing this?

Of course once the page is modified, saved/remixed, and reloaded, the line numbers will no longer match up.

Detecting line text is a good default, but I agree there should be a more powerful way to associate line references with the code.
(Reporter)

Comment 4

6 years ago
@Tom: Wow, magic! Confirmed that it's true and I'm seeing it in production (not just mofostaging).

However, as you say, the real problem is once a project is remixed, the line numbers reset (confirmed on production site).

Not sure on the best solution. ID would work since that's unique. Class is iffy because you wouldn't know which specific class to refer to. A specific data target (as Pomax suggests) might work best, though less intuitive for tutorial creators. Then again, if creators know HTML/CSS, it shouldn't be a problem.

Comment 5

6 years ago
getting this to work automatically across content changes would require making tutorials somehow aware of the identity of lines beyond just the number, so marking as wonfix.
Status: UNCONFIRMED → RESOLVED
Last Resolved: 6 years ago
Resolution: --- → WONTFIX
You need to log in before you can comment on or make changes to this bug.