Improve display of branched guide

[durden]

Currently it's not very obvious when a reader is viewing a branch of a guide. The URL has ?branch= in it but that's the only way to really tell. There are a number of ways we could improve this:

1. Show some kind of banner (maybe just a simple flash message) denoting that we're viewing a branch, not the original.
2. Do the diff (or get it from github API) and display the branched guide text with embedded notes where a change was suggested

Number 2 is much more difficult to implement, but it's a much better UI. I'm not exactly sure of the implementation details, but the end result could look something like the following. Assume we have a guide with the following text:

This is an original guide. Please read it.

Then, assume there's a branch called xyz that changes the guide text to this:

This is an original guide. I would appreciate you reading it.

The branched view could look something like this:

This is an original guide. I would appreciate you reading it. [1]

Then, you could hover over the [1] and see a link to the diff on github or maybe show the original sentence on hover. I'm sure there are better/cleaner ways to show this information. However, this would be a big improvement on what we have now.

[durden]

Another possibility here is using margin notes for the diffs.

[durden]

Any thoughts on this @paulocheque or @prtkgpt?

[paulocheque]

I guess the diff would be line by line. I mean, depending on the change, it would not be feasible to use the margin notes, or we would need to turn the entire line a link and this would be ugly.

So I believe the [1] option would be simpler and better. Maybe some original, master or some self explained icon.

About the backend view, are you referring to this https://github.com/pluralsight/guides-cms/blob/master/pskb_website/views.py#L343 ?

[durden]

I stumbled on this blog post that's semi-related to this subject. The author is exploring the idea of visualizing how a paragraph changes over time. Here's an example showing a paragraph through time.

The display isn't very useful for our purposes because it shows every little change to a paragraph, which would result in too much noise for our long-form guides. However, maybe we can learn something from the experiment.

For example, maybe we could include margin notes on hover of a paragraph. The margin notes could include a list of every revision of the paragraph and/or guide. Then clicking that link would show the guide at that version.

Another idea would be clicking the margin note would show a diff version between the currently visible version and the version clicked.

Any thoughts? @prtkgpt @paulocheque

This is a fringe feature, but it could be very useful for editors and readers of an old, often updated guide.

[paulocheque]

We will have the current/latest version of the article and the past ones. The current version should be, in 99% of the times, the most important version, right?. The past versions should be important only to fix some mistakes, for audition or something.

What I am trying to say is that I dont think the past version are too important to turn the interface more complex because of them. Maybe we could let the article page clean with the latest version, and we could add a button like "history of the article" that links to the GitHub log or to another page only with the diffs.

[durden]

Right, I don't think we should clutter the UI for history purposes. However, the margin notes feature stays out of the way unless you hover over it so that seemed like an unobtrusive way to do this. Again, this is not a critical feature at all. It's more of a cool feature that would be useful for some editors. I'm just detailing the thought process and options here so we could implement this if needed. Also, this issue also allows the discussion to be open to all potential contributors so they could work on this if it's something that sounds useful to them.

[prtkgpt]

@durden That was a great read. Thanks for sharing the link. We should explore this definitely as it's important to tell our audience about the changes and who proposed those changes. I think we can make a proper engagement for editors here by having margin notes like feature. It would be a good thing for contributors page and will grow the list allowing us the better present that data in their user profiles. We can even compile things like stack logos of tutorials I interact with, and # of contributions can earn me certain types of badges. New hack.guides() logo on staging site look pretty good. I like the "BY PLURALSIGHT" as the site still has its look and keeping the balance of our image. On the tutorial page, we can make hack.guides() logo in dark like we currently show hack.summit() in black color.

[paulocheque]

PS: I changed the logo to be black in the PR https://github.com/pluralsight/guides-cms/pull/87