search

exercism / legacy-docs

Other
84 stars 55 forks source link

exercises: Document `title` #98

Closed petertseng closed 7 years ago

petertseng commented 7 years ago

In generated READMEs, the rule for converting an exercise slug to a human-readable form is to capitalise only the first letter of each hyphen-separated word.

For some exercises this is not the best possible title. For example see http://exercism.io/exercises/haskell/rna-transcription/readme and observe that the title is "Rna Transcription", whereas "RNA Transcription" seems more faithful to the rules (RNA, as an initialism, should be in all caps).

For those exercises, we add an optional title field in metadata.yml to allow overriding the default capitalisation or punctuation.

This documents this field and how it is used in README generation.

Discussion: https://github.com/exercism/configlet/issues/76

Addition of title field: https://github.com/exercism/problem-specifications/pull/901

Implementation in configlet: https://github.com/exercism/configlet/pull/85

petertseng commented 7 years ago

Previous discussion in #97: cc645d2 does not seem an appropriate place for the documentation. cc645d2 has been reverted and now we look at 3bf39d4 . It could go in https://github.com/exercism/docs/tree/master/language-tracks/exercises/anatomy, if other lines in the https://github.com/exercism/docs/blob/master/you-can-help/make-up-new-exercises.md get moved as well. I don't wish to claim responsibility for the move.

Insti commented 7 years ago

This looks like a much better initial place for this information 👍

I agree that moving the section (if required) is a separate unrelated PR.

petertseng commented 7 years ago

if the slug is not correctly converted by the default algorithm

I like this. I think it would make sense to say something about what the default algorithm is as a second sentence.

Okay. I have also added another sentence saying to omit the field if the default algorithm converts correctly, let's see how that looks.

petertseng commented 7 years ago

Is the last sentence just defining "optional"?

Hmm. Guilty as charged. The third sentence is probably implicitly apparent from the first. Sort of forgot about that.

But we could "bike-shed" the text for ages. I'm fine with merging what we've got right now.

I'll go with it since it got approvals, I didn't want to re-ask "so what does it look like with the sentence removed" and I guess it doesn't hurt. Except for "perfection is gained not when you have nothing more to add, but nothing more to take away", etc.