Make description.md self contained.

[Insti]

Proposal

The problem description given in description.md should be complete and self contained, and not require the addition of the blurb to make sense.

Components

The description of each exercise is made up of two components:

1. the Blurb
2. the description

The description is appended to the blurb to make the complete problem specification.

(Using pascals-triangle as an example.)

Description

from description.md

In Pascal's Triangle each number is computed by adding the numbers to the right and left of the current position in the previous row.

This is nice but it doesn't say what I am supposed to do.

Blurb

found in metadata.yml

blurb: "Compute Pascal's triangle up to a given number of rows."

Specification

The problem specification becomes:

Compute Pascal's triangle up to a given number of rows.

In Pascal's Triangle each number is computed by adding the numbers to the right and left of the current position in the previous row.

Current Usage

• Blurb is used when giving a short description of the problem. e.g. problems list
• Blurb is combined with the description when creating the track specific readme for a file. e.g. problem readme
• Description is always displayed with the blurb prepended.

Benefits

• The description.md is complete self contained.
• Description pull requests are easier because they only need to edit one file.
• Pull request reviews are easier.
• The blurb contents can be independent of the problem description and can provide an alternate summary if necessary.

Questions and Answers

Q:

Will http://exercism.io/languages/[track]/exercises end up showing the first lines from the description.md files instead of the blurb from the metadata.yml files?

A: No, the description shown on that page will still come from the blurb in metadata.yml

Edit: Added Q&A section

[Insti]

Todo

• Agree that this is a good idea. (No objections so far.)
• Run a script to copy the current blurb into description.md for all problems. (completed: Make description.md self contained. #775)
• Update trackler to no longer add the blurb to the readme. (otherwise the first line of the specification will appear to be repeated.) (completed: Remove blurb from readme. DEPRECATED.trackler#42)

[petertseng]

Since my instinct is to minimise duplication, I'm trying to look for an example of at least one problem where we would like the blurb to be different from the first line in the final specification, and the more of these there are, the more worth it the duplication will be.

In case anyone asks: I confirm that "No objections so far" is true - this comment is not an objection but a curious voice to see where things will go.

[Insti]

The issue with that is that all descriptions have been written the way they are because the blurb is being used as the first line. Once this is done we will start to see them diverge.

[petertseng]

I take that to mean: The more desired divergences we can identify (or predict in the future), the more worth it this will be.

[rpottsoh]

I am fine with this proposal. At quick glance it appears to me that book-store will end up with redundant information in the description.md as the first sentence is essentially the same as the slug. I'd be happy to fix that quickly after this issue is closed.

[ErikSchierboom]

I think this makes sense. Having just one place for the description seems like it would make editing and reviewing a lot easier.

[stkent]

Gigasecond is the worst example of this for me; the description makes very little sense by itself! Great change IMO.