My Contribution to Markdown
leancrew.com
leancrew.com
As a long-term reader of that blog, it is obvious to me this is a little historical anecdote, mostly tongue-in-cheek, from a particular mac-centric community to which both the author and Gruber belong to. He's not being grandiose or trying to take credit.
Sometimes a story is just a story.
Strangers on the internet will come across your little random story if it's public, and rather than blaming first-time readers for not understanding the context nor the voice of the author, maybe the author could adjust the article to provide the context or make the voice stronger/more obvious?
Honestly, I'm fine with not understanding everything from communities I don't generally hang-around, it's bound to happen at one point or another.
I'm not "blaming" anyone. I'm just pointing out that the commenters here are missing the point of the story because they don't understand the context, and that this is a fairly common phenomenon.
I think it's fine to tailor your writing to a community of like-minded readers rather than a first-time reader from here that is unlikely to come back.
> Honestly, I'm fine with not understanding everything from communities I don't generally hang-around, it's bound to happen at one point or another.
Me too, of course. It just makes a discussion without that context, i.e., what's happening here, detached from what the author meant with the post.
The author of the blog post did not submit the article to Hacker News.
Anyway, I wish that HN commenters would apply the same HN guidelines to article authors that they do to each other. It's all too easy to rip on someone who isn't here to explain or defend themselves. https://news.ycombinator.com/newsguidelines.html
That's how the web ends up filled with pablum that offends none but the most easily offended, but draws in the most eyeballs and most upvotes/likes/retweets to become viral.
(I'm pretty sure this was linked on HN, but it's too vague for me to search/find it)
[1] feels like a patio11, or noahpinion thing?
But as the old saying goes, "On the Internet, no one knows you're a dog"
When you take all that out and read what the comic said verbatim with a completely flat newsreader inflection, it will sound really strange and maybe even offensive.
Trevor Noah explains this well here: https://www.youtube.com/watch?v=an3G7F6k6GU
True enough as far as it goes but, if you use that Markdown in some static site generators (SSGs), you may still have to massage it a bit so the SSG output won’t be borked. For a couple of examples:
- In Eleventy and Jekyll (and maybe others), you often have to wrap code blocks in `{% raw %}` and `{% endraw %}`.
- In Hugo, if you're including anything that Go initially “thinks” is real code rather than just a reproduction thereof, you must put comment characters around it: `{{< this >}}` isn't OK, but `{{</* this */>}}` is (and will display in Hugo as the desired `{{< this >}}`).
I don't see how he's taking responsibility for fixing the bug. To me it just sounds like he's sharing an anecdote and this is not entirely serious.
Undoubtedly, as Markdown became more popular, someone else would have pointed out this problem. Gruber himself would have been annoyed by it if he ever needed to write a code block with backslashes in it. But I was there first. And you’re welcome.
In that sentence, it kinda does sound like they're trying to take credit for it.
1. what their doing is in more specific detail
2. what others' doings are in more specific detail
I'm going to assume that the author included all that additional detail in the document on purpose, and with the intent of clarifying what "That's my doing" entails. It seems pretty unlikely that your hypothesis of "the person is claiming the whole thing is their doing and accidentally wrote a whole bunch of words undermining that simple sentence" is the right one.
"I pointed this out in the Markdown mailing list, and Gruber agreed that it should be changed. In the next Markdown release—which was, I believe, his last—he made the change, and all the text in code blocks has been treated literally ever since."
What's wrong with that? He said what he did, said who fixed the issue, and stated the result.
> That’s my doing.
Come on now.
> I
Which clearly means that he takes full credit for the whole Markdown implementation. What a scandal!
It took some time, but they finally implemented it and I felt (and still feel) very good about it :)
Where it starts to feel wrong, would be if you somehow started claiming "I suggested it first. It's because of me it's there. You're welcome", when you merely suggested the feature, not implemented or drove it to be implemented.
Edit: In fairness, I think some of the ways the author describes it are grandiose ("my extremely important contribution"), but I interpreted them as hyperbole.
> . You can paste source code directly into your Markdown document without any changes, and it will appear as expected in the rendered HTML. That’s my doing.
It makes it sound like the author of this blogpost actually did the change, while in reality they suggested the change. Of course it's good to suggest something, and even nicer when whoever you suggest it to implements it. But I'd never claim "that's my doing" after suggesting any features/fixes.
A bit like writing an email to Apple suggesting something, then they do that thing and I wrote a blogpost saying "That's my doing, I was there first. And you’re welcome.". It just doesn't taste well.
That’ll show ‘em! Never write tongue-in-cheek blogs or else random weirdos who will never meet you will write you off as a candidate for an engineering team that doesn’t exist and that you don’t want to join in the first place.
"I made that" is the ultimate statement of pride in work. Taking that away is a really awful anti-pattern in management. Let your people be proud of their contribution, and equally proud of the product of the team. The work of a team is the sum of the contribution of all members.
> a reasonable exaggeration in many circumstances
I find people who take credit for the work of the team to be a lot worse than people who take pride in their contribution to the team.
But if they use the same language to describe the entirety of a team project, not just their contribution, as "my doing" alone, that often crosses a line into toxicity in the ways you mention in your second paragraph.
Obviously the "it doesn't work" bug reports are worthless.
Had this one project where I converted it over to python 3 in a fork and they merged the whole thing without a mention of where they got it from. Kind of sucks but ultimately didn’t matter because I was doing it for my own usage. Plus it made my life a little easier because I didn’t have to maintain it separately, just fire and forget a bug fix whenever it came up.
If I was doing Resume Driven Development I would probably care a little more though.
https://i.kym-cdn.com/photos/images/newsfeed/001/079/173/ed2...
1. Finding the bug was difficult, while fixing the bug was trivial
2. My own proposed patches seem to sit for years, while emailing bug reports directly to the committer results in them committing fixes within days.
- list: https://twitter.com/swyx/status/1240719259505963010 (previously on HN https://news.ycombinator.com/item?id=22776108 )
- gruber: https://twitter.com/gruber/status/1240888155307495426
https://talk.commonmark.org/t/cross-references-and-citations...
Is the tweeted list a little outdated now?
> no id's in headers
A natural ID is derived by changing the header to lowercase and replacing spaces with hyphens, such as:
https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
> no syntax for adding classes
Pandoc introduced ::: annotation blocks that produce div tags with classes. I discuss this length:
https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...
My editor, KeenWrite[0], also supports annotation syntax:
https://user-images.githubusercontent.com/2131950/161400266-...
> any number will do in ordered lists
Isn't that either a presentation issue or a feature? I prefer numbering lists with a sequence of 1., 1., 1., 1., to let the computer automatically increment the number. Makes adding/removing items easier. Being able to arbitrarily change the numbering seems weird, though potentially useful.
> code blocks (4 spaces) over code fences (```)
Not sure why this is a design mistake. When reading technical documentation, indented stands out more. IMO, it improves readability for short snippets (where syntax highlighting doesn't matter).
> can't nest Markdown in HTML in Markdown
Depends on the Markdown flavour, doesn't it?
<script type="text/plain">
> hello world <- this is legal
</script>https://developer.mozilla.org/en-US/docs/Web/HTML/Element/xm...
I think HTML should have a dedicated tag for this, but sadly <script> is the closest thing that I know of.
MarkDown didn’t have any standards to begin with, just different implementations for different platforms. Tired 927 refuted.
Sometimes I want to highlight a part of the code...
This is clearly spec'd and has clear expectations on how it should behave. No implementation details of course which you wouldn't expect from a product manager in most cases as well.
> The code block has to be indented, of course, or—in many implementations, but not Gruber’s—surrounded by fences.
Indenting is always a nuisance and can present more complicated problems for Python or other whitespace-significant languages.
CommonMark and most Markdown flavors support 3 backticks or 3 tildes as a fence. Then everything inside is literally unaltered code. Not sure what you do if your code sample itself has the fence in it.
With these things, I always think "but if he hadn't done it, someone else would". Therefore, what matters is the thing that got done; the person doing it isn't special (nor should they feel so).
> Undoubtedly, as Markdown became more popular, someone else would have pointed out this problem. Gruber himself would have been annoyed by it if he ever needed to write a code block with backslashes in it.
People are overreacting to a tongue-in-cheek post. I doubt the author takes himself too seriously with all of this.
But the rest comes off like mock humility because there really wasn't any information of relevance to anyone but the author.
Had the article been about the importance of user engagement in open source projects and then used his personal experience to underscore the point, then the article is really about raising awareness and might be something of utility to a reader. This article, however, just reads like me, me, me.
Heck, what is the purpose of my comment?