[Haskell-cafe] Markdown extension for Haddock as a GSoC project

[Richard A. O'Keefe]

On 29/04/2013, at 4:18 PM, Chris Smith wrote:
> 
> My point was not anything at all to do with programming.  It was about writing comments, which is fundamentally a communication activity.  That makes a difference.  It's important to keep in mind that the worst possible consequence of getting corner cases wrong here is likely that some documentation will be confusing because the numbering is messed up in an ordered list.

The problem is not what it does to the formatting.

The problem is what it does to *PEOPLE*.

It wastes their time.

Suppose there are 10,000 Haskell programmers (I have no idea what
the true number of Haskell programmers who like to document is; I
hope it's more) and they lose just 6 minutes a day working around
glitches in their documentation tools.  That's 1000 hours a day;
call it 40 days of human life blown away in aggravation every day.

To quote Jayne, "Where does that get to be fun?"

Why is it acceptable to waste anyone's time with "confusing"
documentation?

Did anyone else read that Markdown-in-Haskell mentioned here recently
whose author comments (quoting from memory) "any random string of garbage
is legal Markdown", so that there is no possibility of catching errors
early; by definition in that processor there are no errors.

> Pointing out that different processors treat markdown differently with respect to bold or italics and such is ultimately missing the point.

It may be missing your point, but it hits mine square in
the bulls-eye.  It wasn't just that they were *different*,
it was that the difference wasn't *documented*, and I had
to waste an hour of my *LIFE* that I will never get back
because some lazy swine couldn't be buggered doing
documentation.

About a documentation tool.

Savour the irony!

> That doesn't mean the choices should not be documented.  Sure they should.

If we agree that the semantics should be documented,
what are we arguing about?

>  But it seems ridiculous to sidetrack the proposal to do something nice by concerns about the minutiae of the syntax.

Nobody is suggesting that the proposal should be *CHANGED*.
So talk about "sidetrack" is unwarranted.
The pathetic request from a suffering humanity is that
the mark(up/down/sideways) should be *DOCUMENTED* clearly.

As for "minutiae of the syntax", *you* may call the fact that
`` in the middle of a line and `` at the beginning of a line
do different things "minutiae of the syntax", but *I* call it
"wantonly squandering my few remaining hours because you think
that no or confusing documentation is OK".

The more I use Markdown, the better HTML looks.
That is, the more effective HTML looks *AS A COMMUNICATION TOOL*,
where effectiveness is measured in terms of the effort required
to get the result you want.

Other people may have other experiences, and that's wonderful.
Having better documentation WILL NOT HURT THEM.