Conveying better a change in code for new developers

[ijlee2]

Background

In the Ember Guides, we use the + and - to indicate what code have been added or deleted. For example, in the Super Rentals Tutorial (and other pages outside of the tutorial), we might see,

I recently met a developer who works with 2 interns. The interns weren't sure how to read such code, and attempted to copy-paste all lines of code into their editor. The developer explained to me that the interns weren't yet familiar with diff tools that we (e.g. people who have been a developer for some time) might regularly use on GitHub.

For more complex code (think about a large code review that you might have had to do), I think it's also possible that showing many changes with + or - may not be the best way to convey the changes.

I wondered if we can update the code block component to either:

• Provide a help/info button that, when clicked, explains how to read code with + and -
• Provide an option to see Before and After side-by-side (à la Octane cheat sheet)

Summary of Learning Team meeting

Link to the meeting notes

On September 17, we (Learning Team) discussed if this feedback had been presented to us before (yes) and how we can better present a diff in code for new developers.

We arrived at the ideas to:

• Update the code block component (we'll use ember-showdown-prism from now on) to render an info button when the component detects code with + or -

• Reach out to the entire Learning Team (not everyone was able to attend the meeting) and @chancancode, in particular, to coordinate how we can make changes to code samples for the Ember Guides

  The exact change will likely depend on the surrounding context. We could take one of these options:

  • Option 1. Always show the after code.
  • Option 2. Show before and after code in the same code block, but add comments // Before and // After to separate them.

[chancancode]

I would love to make this a component that has a toggle for "Before" / "After" / "Both", defaulting to "After" (and "Both" is the current view). I have brought this up before as well.

[MelSumner]

I don't think we should take it out- Code diffs are something all devs encounter. We can add an explanation for new developers, though. 👍

[ijlee2]

Thanks for a quick reply! I'm glad to hear that we agree on providing a better experience for new developers.

To provide more context into today's meeting, Chris mentioned that there may be a technical difficulty with implementing a toggle/tab for Before and After. (We may need to add metadata to code sample to denote which line belongs to Before and which line to After.)

Info button, in comparison, may be easier to implement.

[chancancode]

This is roughly how I would like it to work:

As for metadata – I am pretty sure we already have what we need to implement it. There is a data-diff attribute that has the added/removed lines. Plus, the added/removed lines are wrapped in a span.diff-deletion/diff-insertion that could be easily identified or even shown/hidden with CSS.

[imagolive]

Hi All, I mentioned to Isaac about the diffs and the interns. The interns struggled mainly because they had only worked on traditional apps and not templated/data-driven approaches. Data down/actions up and tracking didn't fit into their world view. The diffs made it a little harder for them to understand.

The above mockup is much better, particularly if the After is the default view.

[acorncom]

Is there a difference from an a11y perspective with these two approaches? In the absence of problems there, the before / after / diff option seems like it’d be great, as those diffs have been causing some confusion for a long time

[mansona]

This conversation bubbled out into Discord (you can check it out here) and I thought I would share my top-level thoughts on the proposal:

the main objections to an implementation like that is that we can't effectively write Markdown that would adequately express the example that you have. Yes we can make it work for sure in an Ember app, but that also brings up a whole bunch of other questions like: what does it look like in the fastboot render before the app boots, what is the behaviour of the app never boots, how do we actually use this component if we're writing in markdown.

for sure there are a number of things that we can do like maybe rending Ember components directly in Markdown, and in fact I'm doing that in Field Guide right now but that has a very large cost currently in that we need to ship the Template compiler as part of the bundle to have this work. Because of the design of the guides as a static docs site we don't want to do this yet

there are some more corrections and explanations in the discord conversation that I linked, but essentially I would be very much in favour of just removing the need for diffs in the guides as much as possible. We can then discuss some basic implementation that could make it easier for people to understand the diffs in older versions of the guides 👍

[ijlee2]

@mansona No problem. I appreciate your feedback on the implementation!

[ijlee2]

@acorncom I'm not sure off the top of my head, and would need to research. I agree that accessibility is an important factor to arriving at a solution.

[ijlee2]

The Learning Team didn't get to discuss this item on September 24 (we focused on Hacktoberfest). We will try to revisit it on October 1.