Article snippets

Exercism
1

This is a question probably for wider consideration, but specifically about C# track and an article I’m trying to publish.

In short: Does every article benefit from a snippet? Should every article have one?

When it comes to Approaches then a snippet of the solution makes sense as this illustrates what’s in the article / approach. It is not always perfect as the recommendation to use 8 lines of code or less, and the limitation of side bar having only enough space for the first 40 characters, but it sort of works.

I have noticed that on the C# track the current convention is to add a table with performance data in articles relating to performance. It makes sense, but this is how it looks:

image
image856×948 101 KB

A lot of text which, in my opinion, offers very little to people familiar with BenchmarkDotNet output format, and even less to people who don’t know about benchmarking and would like to learn about it. The problem is that the table is not visible as the snippet is formatted as code. There is also a lot of information there which doesn’t tell us anything except of the names of methods used to test performance. As a result, the information needed for a reader to decide whether to read the article or not is far lower and less standing out. I think in this case the snippet is counterproductive.

But what should be the snippet for an article that doesn’t cover a specific solution, or performance? I tried to have this:

public bool IsPalindrome(int number)
{
  /* see possible implementations */ 
}

or something similar, but @ErikSchierboom quickly pointed out that it is not very informative, just to see that comment. I agree, but neither are the alternatives in my opinion.

So, I wanted to start a discussion here. What is the purpose of a snippet? Does every article need to have a snippet? If so, what should it be for it to be helpful in meeting that purpose? But wouldn’t it be better not to have a snippet for an article that doesn’t have an obvious one?

Let me know what you think.

2

I agree that these are sensible and interesting questions.

Some articles might have more use for an image than for a code snippet. I’m thinking time/residency graphs, illustrations of strategies or proofs, screenshots of tools, …

3

Well, yes and yes IMHO :) I can understand why the table might not be optimal, so I’m open to other suggestions. But the snippet is a key way for users to get a feel for what the article is about. It could even be regular text.

4

My point is that a snippet that is not formatted as a table and not key to the article doesn’t serve the purpose as a “key way for users to get a feel for what the article is about”. In some cases, perhaps, a good description and title would be better for that.

Adding text as a snippet will make it still render as code and result in worse user experience than if the same text was put in the blurb and displayed as text under the title.

(I have just realised that I have many “pending” comments on that PR, among other things about that! I’m trying to fix it now!")

5

Let’s be clear on terminology here.

This suggests to me that, to Erik, a «snippet» is whatever is displayed where currently the code snippets are shown. Is this correct, @ErikSchierboom?

If so, then I do not yet see a disagreement.

6

This is not true though. Article snippets are just regular markdown.

Correct.