web: "Related Cards" inconsistencies

[Nilhcem]

How to handle "related card" references?
Should we specify them in their own section, in a single-line entry (as in hurt-often, poutsma-principle), or in multiple entries (as in acceptance-criteria) ?

Some other inconsistencies:

• done.md: "Related cards" is not written in the right place, we should also replace ## Code Review by ### References
• two-minute-rule.md: related cards have no link

[barend]

The related cards were, originally, a section at the bottom of the document. I've come to prefer to have them throughout the text where relevant, like links on Wikipedia. I believe that will make it more likely that people stay on the site for longer.

[jbnicolai]

Why not both?

I was thinking of adding a YAML front matter array of related cards, which would be added to be bottom when generating the site.

[barend]

That sounds like a nice addition.

[jbnicolai]

Create a pull request with a proof of contept on http://essentials.xebia.com/two-minute-rule/

• Related cards are part of the markdown metadata
• They get parsed and placed on the bottom of the page in an unordered list
• The names get split and capitalized, transforming team-member-equality into Team Member Equality

[jbnicolai]

Possible improvement:

Define a markdown extension for cards, say [%], e.g. [%two-minute-rule].
Replaces all occurences of [%] with the filter from #9
Push all occurences of [%] onto references, causing them to be listed at the bottom as well.

This would transform:

---
related:
  - card-from-the-top
---

### Some Text
A reference to [%card-from-the-text]

Into:

Some Text

A reference to Card From The Text

References

• Card From The Top
• Card From The Text

[jbnicolai]

Implemented my previous suggestion,

see http://essentials.xebia.com/what-you-measure/ and be38a37#diff-ba6b642bd92f2aa59313bae53eb5eb81

Cards can now be either prefixed with an array of references, or references can be created inline with %. Both will be added under the 'references' section.

[jbnicolai]

Any feedback on this? Examples can be seen in the source and generated pages for

• http://essentials.xebia.com/two-minute-rule/
• http://essentials.xebia.com/what-you-measure/

Upside:

I think it's pretty nice

Downside:

Someone will have to go through all cards and implement this

[Nilhcem]

I like the way of browsing the cards throughout the text directly. It's very nice.

Should we distinguish somehow (icon/color?) links that lead to different cards from links to external sites, or is it unnecessary?