5 ms·
I thought Markdown was clearly very silly back when it started gaining traction amongst developer types. There were already so many other better options--even a
by bityard 2y ago
I thought Markdown was clearly very silly back when it started gaining traction amongst developer types. There were already so many other better options--even at the time--for plaintext-to-formatted document markup languages.) But still, developers were designing whole apps (CMSes, productivity apps, document management, etc) and plugins around Markdown, sometimes as businesses.
But then I realized, after using it in some apps, that wasn't really what Markdown was about. Markdown is about a bare-minimum amount of styling that is just as readable and at home in plaintext as formatted in HTML. The amount of formatting it supports is small _on purpose_, so that it fits in your brain and doesn't require a toolbar to use. It is _meant_ for things like comment fields, chat programs, commit messages, and so on. Maybe even blog articles. But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.
These days, I write Markdown even in place where it will never be rendered into HTML. Because it's quite readable as-is. (And I wish HN supported it.)
- packetlost 2y ago> But it certainly is not something you'd want for writing the documentation for an enterprise-grade product. I guess that depends. If you're making a print manual, yeah probably not. IME markdown gets painful as soon as you start doing a bunch of tables. Most enterprise web applications would probably be completely fine with just markdown-based docs.
- paholg 2y agoI think a good example is all of the wonderful documentation that's been created with mdBook. Heck, the Rust book was written with it, and they also made a print edition, so maybe markdown is enough even for that. https://github.com/rust-lang/mdBook https://github.com/rust-lang/mdBook
- steveklabnik 2y agoCarol put in a tremendous amount of work to build tooling to go between Markdown and Docx. The publishers used the docx versions for print. That doesn’t mean that I think Markdown is inadequate or the wrong decision, but it’s not just a “write in Markdown and you’re good” sort of situation.
- paholg 2y agoAh, good to know! Is that tooling public anywhere, or was it pretty tailor-made just for the Rust book?
- steveklabnik 2y agoBoth public and tailor-made: https://github.com/rust-lang/book/tree/main/tools https://github.com/rust-lang/book/tree/main/tools
- paholg 2y agoAwesome! You and Carol rock!
- steveklabnik 2y agoThanks! She gets 100% of the credit in this case though :)
- brnt 2y agoI can find here the process of converting docx to md, but not the reverse. I see the material is checked into the repo in both formats. Does that mean the docx's are your master, and you generate the markdown from it for diffing and building HTML? I'm investigating how to switch an organisation away from a docx-only mess of a documentation system, and it looks like you might have found a process that'd work for us, and let people keep using docx if they have to. I wonder what all those binary blobs do to the git repo though. Thanks for any info!
- steveklabnik 2y agoYou'd have to ask Carol, with the way we split the work, she handled all of this. From my perspective, the markdown was the master copy. Sorry I can't be of more help!
- Terretta 2y agoThe link below (https://github.com/rust-lang/book/tree/main/tools https://github.com/rust-lang/book/tree/main/tools) could imply the book was written as Word .docx with named styles, which enabled transformation into markdown for the mdBook?
- tetha 2y agoI arrived at a similar conclusion, just from the other direction: It is really hard to get people to document. It is even harder to get those people to care a little bit about formatting. Markdown is... limited, I acknowledge. But with a very small amount of learning, markdown is as fluent and simple to write as normal text. In fact, 90% of what I wrote before I knew markdown was valid and decently formatted markdown already. If you asked people who don't document to document in rST or tex... then you'd have no documentation at all. Because that suddenly adds a lot of effort on top of what you want to write down. Now for some customer-facing whitepapers and documentation, we do use rST. But there you have people who are tasked with paying some effort to create some decently looking docs. Not trying to coax developers into writing down some of their state of mind while doing stuff.
- unethical_ban 2y agoYes! Markdown is great because it is a way to write and store documentation in plaintext, in a way non-documentarians can follow.
- duskwuff 2y agoAnd it's been making a ton of headway even outside that context -- I've seen occasional formatting goofs in online newspaper articles that indicated they were authoring their content in Markdown. (Which makes sense! News rarely requires complex formatting.)
- eru 2y agoYes, though I would expect most news-folks to use some form of WYSIWYG for writing?
- zelphirkalt 2y agoAlthough, I have to say, it is a sad state of afairs, if rST is already too difficult for a person with the job role "programmer" to use. If this is already the threshold, which would stop them from writing documentation, then I have my doubts about the quality of documentation, that they will write in Markdown.
- keybored 2y agoMarkdown is like a virus of an idea: 1. Apparently simple enough to implement to get the basics right (not that I could do it) 2. But there is plenty of room for accidental edge cases in the implementation 3. Many then implement it with or without edge cases 4. But it’s not enough because a lot of the people who use it are programmers so they naturally want to extend it to do just a little more 5. Now the standardization effort (Commonmark) has to take all of those edge cases into account plus have to figure out how to deal with extensions (especially for popular ones) 6. Then you get a heroically (in terms of effort and grit) wordy standard All for the initial idea which is so simple that it seems redundant: look as good plain as rendered. (Then what’s the point of rendering it, and in turn what’s the point of a formal syntax instead of the (still existing) ad hoc email and whatnot conventions?) Right now it’s fantastic for chat applications (here you definitely want rendering and not the visible markup). It’s been pretty good for things like forum comments as well. With the exception of block quotes which are a pain to fiddle with (the only prefix syntax if you don’t include the indentation-for-code since that is de facto optional now that so many applications support code fences… all because that’s how email does it).
- bitwize 2y agoMarkdown is the Unix of rich text formats.
- cqqxo4zV46cp 2y agoTo be fair, John Gruber offered up a completely deficient “standard” and a buggy as hell Perl parser implementation. Yet still wears “I created markdown” as a feather in his cap, strongly insists to this day that it was a good idea, and says “the canonical markdown docs are on my blog! Nothing else is markdown!” Things like CommonMark were absolutely integral to Markdown’s current success. It was way more about fixing John’s mistakes than adding more functionality.
- rcarmo 2y agoYeah, I still have thousands of Textile pages, but all of my newer stuff is in Markdown…
- hinkley 2y agoAs we’ve gone horizontal on tool chains instead of vertical like we used to, what you want is a bunch of mentally cheap tools with high bang for the buck. Get in, get out, move on to the next of fifty tools you have to deal with each week.
- tjoff 2y ago>Markdown is about a bare-minimum amount of styling that is just as readable and at home in plaintext as formatted in HTML. My gripe is that it really isn't. Because markdown inevitable includes images or something and the instant it does it doesn't hold up to it's killer feature. Now you can't read it properly, so now you have to find a generated version, or hunt down the images manually, or generate the output yourself. Alternatively, the document is so trivial that even markdown formatting is too much (just distracts) and doesn't add anything of value. It isn't that bad, it just never seems to make any sense for files. It does make sense for web forms though but that's only because you never read the markdown, you just write it and the output is generated on the fly.
- 8organicbits 2y agoWhen you use one of the extensions, like Hugo's figure, which has alt-text support you're about as close to that goal as possible. An image can't be stored in human readable plain text. The alternative is WYSIWYG formats that aren't plain text.
- tjoff 2y agoDoesn't matter how close to the goal you get if it is on the outside... I'm gonna be annoyed if I clone your repo, open the readme.md and now have to figure out how to read it. Plain text is awesome, for plain text. If it isn't plain text might as well use a pdf.
- 8organicbits 2y agoThere's no reason for this to be all or nothing. This seems perfectly readable to me:  Even if you've never seen markdown before, it's pretty obvious.
- AndIHateLatex 2y agoI'm having a bit of trouble understanding the problem here as well, and kinda hope people expand on it, because insight might think of what to do better. I edit a number of wikis. This leads to an inevitable amount of instances of having images floating aside the the text. Sometimes there's some peculiar stuff done with tables. But we never actually intermix the text content in a completely unreadable way, at least outside of templates and modules, which are NOT text content meant to be read in the first place and are NOT markdown either. Every section of text only has text content, and the only alterations to the text come as syntax that strictly surrounds the affected text. If images have peculiar formatting demands, they will exist outside of text (Such as a CLR).
- SPBS 2y ago> But it certainly is not something you'd want for writing the documentation for an enterprise-grade product. MDN documentation is written in markdown. I’ve always felt this was a resounding endorsement of markdown over other more “powerful” markup languages because if they can do it, why can’t you? (not you in particular, but anyone who thinks markdown is inadequate for docs) https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN https://developer.mozilla.org/en-US/docs/MDN/Writing_guideli...
- red_admiral 2y agoAll my documentation at work is written in a dialect of markdown. It's absolutely the thing you want, together with a good parser and content management system for producing a site with search, navigation etc.
- jgruber 2y agoWell said. But, uh, there’s no “maybe” about Markdown being intended for writing a blog. That’s literally exactly what I made it for — for me to write Daring Fireball.