[general] Ambiguity in the x-common README.md

[guntbert]

README.md states

There are three metadata files:
description.md - the basic problem description
metadata.yml - additional information about the problem, such as where it came from
canonical-data.json (optional) - standardized test inputs and outputs that can be used to implement the problem

1. I would expect to find in description.md a clear description of the task at hand (like: "Write a program that takes a number and decides if this number ...") - but there are cases where this statement is completely missing (see [perfect-numbers] Description is not clear #447) or is to be found in metadata.yml (see https://github.com/exercism/x-common/tree/master/exercises/triangle).

The README.md gives no precise guidance here.

2. generally metadata.yml contains

source

and

source url

I would expect this URL (if existing) to point to something like a good description of the problem/task and not

• just to a page with "many" problems (e.g. http://rubykoans.com in triangle)
• or even to a book that seems to contain that problem (e.g. http://shop.oreilly.com/product/0636920029687.do in perfect-numbers)

As before the README.md doesn't give precise guidance what should be provided.

[kotp]

Please do modify the title to which exercise this is directed to. Something like [triangle] Ambiguity in README.md

This could be a problem in general to address though... But I see the body of the issue picks on Triangle exercise.

[guntbert]

@kotp This is a general issue (the mentioned exercises are just examples). I was looking at #447 (perfect-numbers), then at triangle and noticed that the information provided in both cases was not consistent.

So I reread the README.md to decide where I could improve informations and found a lack of guidance - what kind of information is expected in which file?

[kotp]

OK, thanks. I wasn't clear on that, though saw the possibility it was "generally".

[petertseng]

The situation in the API package delivering the exercises:

As seen in assemble_readme and Problem, the blurb line from the metadata.yml file is prepended to the description.md file. note 2017_06_22: this is no longer true

I would suggest that the README of this repo be updated to match the current situation, unless something in Trackler changes. As I understand it: The metadata should contain a blurb with a one-line description of the task at hand (in addition to what it already has). description.md contains a longer description, and the blurb will be prepended to it on delivery.

I would expect this URL (if existing) to point to something like a good description of the problem/task

I agree that this is preferable.

[Insti]

I've been meaning to argue the case that the description should be self contained and the blurb should NOT be prepended to the Readme.

[petertseng]

the blurb should NOT be prepended to the Readme.

Reminder to us to revert #386 and #533 if that happens.

[Insti]

I've been meaning to argue the case that the description should be self contained and the blurb should NOT be prepended to the Readme.

Done: #767

Reminder to us to revert #386 and #533 if that happens.

Updating all the descriptions will be part of the process so it should not be necessary to remember these ones specifically.