10 ms·

Say Yes to Markdown, No to MS Word

97 points by drodil 9y ago

deleted 9y ago
[deleted]
geogra4 9y ago
I want to use markdown for our technical documents. But MS Word really has some features that are missing that would be needed for a markdown editor to make a dent in what we need. 1. auto-generating table of contents 2. easy table creation/manipulation 3. header/footer and page numbering 4. comments/edits (maybe integrated with git?) It's unrealistic to expect non-technical people to learn LaTeX, so we're stuck with MS Word until someone makes an amazing Markdown editor that can handle these things.
- drodil 9y ago
  Very good point. There would be an awesome opportunity for some software engineer to create such editor (cross-platform of course). Also it could support other markup languages such as Textile as they don't differ from each other so much. Also what would help this is that the Markdown was standardized and would have these features included out-of-the-box.
  - xienze 9y ago
    > Also what would help this is that the Markdown was standardized and would have these features included out-of-the-box. There is technically a standard Markdown dialect called CommonMark. The main problem with it is that its specification is example-driven and there's lots of places where things are up for interpretation, but for the most part it achieves its goal. What it really needs is standardization of extensions like tables, diagrams, etc.
- j_4 9y ago
  3. is automatically added and easy to adjust when using the Markdown PDF extension for VS Code.[1] [1]: https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf https://marketplace.visualstudio.com/items?itemName=yzane.ma...
- oneeyedpigeon 9y ago
  Well, markdown files are just plain text, so you get the git integration 'for free'. As for 2&3, this is why I author documents in HTML: about the same level of complexity as MD, but far, far more powerful. 1, I'll give you, is an issue, just one I don't even run into (I tend not to be editing documents so huge that they demand a ToC).
  - geogra4 9y ago
    We do a lot of large design/spec documents so we really make a lot of use of that.
    - oneeyedpigeon 9y ago
      I think if I had that use-case, I would consider writing a small piece of javascript to generate the ToC. Maybe even possible with CSS, although it could well be too hack-ish for that approach.
- cup-of-tea 9y ago
  Org-mode can do all of those things.
  - geogra4 9y ago
    Emacs is going to be just as obtuse for your everyday business analyst as LaTeX
    - eadmund 9y ago
      The original emacs paper[0] noted that many of the users who started programming were secretaries who didn't know that they could. Learning how to truly use a computer is as important in the 21st century as learning to read was in the 19th: those who find emacs obtuse need to learn it just as certainly as those who found letters confusing. [0] https://www.gnu.org/software/emacs/emacs-paper.html#SEC29 https://www.gnu.org/software/emacs/emacs-paper.html#SEC29
      - cup-of-tea 9y ago
        Yes, it is unfortunate that so many use computer-shaped devices but only a very small number actually do computing. The rise of point-and-click has done a really good job of hiding the possibilities from people. Eben Moglen likened point-and-click to a "caveman interface" where your only options are pointing and grunting, as opposed to using language to communicate your ideas. Only programmers do the latter but that is a shame.
        deckard1 9y ago
        > Only programmers do the latter but that is a shame. Part of me says this is job security for software developers. The other part of me saw non-programmers try to use Excel as a layout/desktop publishing/vector graphics tool. But seriously, if you know how to program and you do literally anything else, then you become a developer. It's the cushiest job with the highest pay. The other reason it will never happen is because the developer's job isn't to make the office worker more efficient (that's Microsoft's job, so I suppose some developer does it, just not all developers). The developer's job is to increase efficiency. Either internal efficiency, or external efficiency. And that means: jobs will be lost. Rather than training office workers how to program and have them leave for a developer job, it's better to just pay developers and have them automate an entire class of office workers' jobs. Hopefully all developers get the opportunity to witness internal efficiency planning. Most developers are disconnected from the process. But to actually meet the people you're going to eliminate with software in a month or two is truly something.
- adzicg 9y ago
  "pandoc --toc" puts a TOC in when creating pdf files. You can also use "--toc-depth=XXX" to select how many levels of headings you want in the toc. page numbers also get added automatically I think when using the book docclass.
- lloeki 9y ago
  Our needs are simple, so we have something† based on kramdown (in GFM mode) and tilt-pdf[0] (shameless plug) which generates a TOC, handles styles, headers/footers, and leverages wkhtmltopdf††. Documentation is in git as markdown files, linted, generated, and published as part of CI/CD. Comments/edits are done though GitLab MRs implementing an editorial review process. Occasional contributions are done through GitLab web editor, and more involved non-technical people use VSCode to sync, write, and commit. The GitLab flow of (Issue->Branch->MR)->(Fetch->Edit->Commit->Push)->(Review->Merge->Publish) is quite assisted and works quite well with open-minded non-tech people. [0]: https://github.com/lloeki/tilt-pdf https://github.com/lloeki/tilt-pdf † The tool should be open-sourced as soon as we can clean up the code of hardcoded internal stuff. It'll appear over there: https://github.com/adhoc-gti/makebook https://github.com/adhoc-gti/makebook †† Contemplating moving to headless Chrome. Also, increasingly using Hugo for online documentation.
  - geogra4 9y ago
    This looks really neat! I'd love to experiment with this
  - pzb 9y ago
    I've been working on a similar system that is in the process of being adopted by at least one standards group (https://github.com/cabforum/documents https://github.com/cabforum/documents ). I would strongly recommend looking at weasyprint (http://weasyprint.org/ http://weasyprint.org/ ) for HTML to PDF. It gives much better PDF output and offers CSS print support, so you get page control.
- shadowfiend 9y ago
  asciidoc via asciidoctor (https://asciidoctor.org https://asciidoctor.org) covers a lot of this, though not bundled into a system. Comments/edits via something like GitHub, tables (https://asciidoctor.org/docs/user-manual/#tables https://asciidoctor.org/docs/user-manual/#tables), tables of contents (https://asciidoctor.org/docs/user-manual/#user-toc https://asciidoctor.org/docs/user-manual/#user-toc), and with some docbook work (admittedly annoying), you can get header/footer and page number (https://asciidoctor.org/docs/user-manual/#docinfo-file https://asciidoctor.org/docs/user-manual/#docinfo-file). It's not perfect, but it's very similar in concept to Markdown, has several adaptations to make the md->adoc transition easier, and is much more feature-rich, thanks to being based on Docbook (which is used for creating much more complicated documents than Markdown historically has been).
  - castillar76 9y ago
    Agreed. As someone that manages multiple documents under heavy revision control in a public repository (yay, public certificate authority documentation), Asciidoc has been a life-saver. We used Word for a long time, but found it was way too difficult to track revisions and approvals using it. Inevitably, you'd pass the document to eight people that need to approve and get back eight sets of changes, which you then have to integrate in and hope no one has introduced a regression from "DOCUMENT_JONREVIEW_VERSION1_COMMENTS_FINAL_FINAL_DRAFT_FINAL_DRAFT_FINAL_COMMENTS_V6". Moreover, the people doing the reviews are a mix of technical and non-technical, and doing the review/approval process in Word docs meant constructing an Alfresco instance or similar to track the approvals and validate for auditors that we'd completed reviews before pushing updates. Also, you have to create something to keep track of the Word document originals /and/ the PDFs they produce—it always seemed like the Word originals would disappear at some point, leaving everyone to back-create them from the PDFs. Now we do the documents in AsciiDoc, and track everything in an internal Github repository using pull requests. The diffs are clean and are actually easier to read: you can comment, you can immediately see where the changes are, and everyone is focused on changes in content rather than getting distracted by font and spacing choices. Once N people out of M have approved the pull request, I can merge it into the master and then publish it into a clean, readable PDF with an auto-generated table of contents, page numbers, footers, and the like. Now, if someone were to invent a WYSIWYG app for Asciidoc, that would be awesome, but this seems to be working a whole heck of a lot better than the previous Word-based method.
donquichotte 9y ago
Ooooh man, I would love to do that. I enjoy writing markdown, and I enjoy using pandoc. However, whenever I have to print something, there is pretty much just one possibility in Markdown: export as pdf. And export as pdf uses Latex. Latex is cool. But if you want to customize your document, you will sooner or later need to include latex headers into the "build" process of your file, and soon you have a clusterfuck of tooling and a make file for a document that was supposed to be a simple report. And then I'd rather write it in Latex. Does anybody have a solution for this? Some kind of print-friendly Markdown-to-PDF workflow? All the non-Latex alternatives looked horrible. In fact, I sometimes export markdown documents to Word just to print them.
- xienze 9y ago
  MD->HTML->PDF. Just use a browser to render your document. You can make the process a bit more automated by using something like Chrome Headless. I'm sure there's a project out there that does this all in one step from the commandline.
  - donquichotte 9y ago
    This approach is what I have sometimes been using. It works OK and I can style my documents with CSS. But there are little things that bug me, like headlines on the last line of page N and the paragraph starting on page N+1 and header/footer lines generated by the browser.
    - laxis 9y ago
      for what it's worth you can define pagebreaks with css [0]. it's not the most user-friendly way, but works. the @page rule also comes in quite handy [0]: https://developer.mozilla.org/en-US/docs/Web/CSS/page-break-inside https://developer.mozilla.org/en-US/docs/Web/CSS/page-break-...
  - nathan_long 9y ago
    My setup: 1) I have cmark installed 2) https://github.com/nathanl/.dotfiles/blob/master/bin/md_preview https://github.com/nathanl/.dotfiles/blob/master/bin/md_prev... is a script to render STDIN to HTML and slap the output into the middle of a template that has some basic CSS (https://github.com/nathanl/.dotfiles/blob/master/bin/md_preview_template.html https://github.com/nathanl/.dotfiles/blob/master/bin/md_prev...) 3) I write markdown in Vim and use keybindings to say "now output HTML from this buffer" - https://github.com/nathanl/.dotfiles/blob/ede8c98a7897ee07b724b4225c2ac3a765341c25/vim/vimrc#L299-L302 https://github.com/nathanl/.dotfiles/blob/ede8c98a7897ee07b7... I like this mainly because it lets me use Vim, which for me is the most efficient tool for wrangling text. I also like avoiding WISYWIG programs that I previously fought with - eg, trying to get Word to understand which bullet points I wanted nested under which other ones was frustrating, but with markdown (and embedded HTML when necessary) I can be 100% explicit. Sometimes I copy-paste the resulting HTML into Google Docs or elsewhere and do further tweaks, but most of the time it's enough for me as-is.
Proven 9y ago
Bullshit. Word is a nice editor and can edit Markdown files too. There’s also a free add-on that makes it easier to handle the MD format.
cup-of-tea 9y ago
Right now I'm writing a document in plain text. Not markdown but org-mode. I could export it as markdown for collaboration purposes easily enough. What I will get at the end is a higher quality document than most Word users will produce but with a minimal amount of effort. The thing is a document only really contains a handful of different elements. Therefore you only need a handful of styles. What you do is make a template document for pandoc in the format of your choice (e.g. MS Word) and then your markdown/org-mode document can be automatically converted into that style. The problem with Word is it makes choosing ad-hoc styles really easy instead of promoting the use of styles. It has developed a culture of people who think about text being "bold" rather than text being "a heading" or "emphasised" etc. We teach this distinctionfor HTML and CSS (and it is, to some extent, used) but for some reason still use Word for writing documents.
- zokier 9y ago
  Styles have been best practice in Word too for decades. And in current versions the styles portion is like half of the default "home" ribbon, with big buttons and fancy live previews and all, so you can't really argue that they would be especially hidden in the UI. Still, it is true that your average Word user still typically produces fairly horrible documents. Why is that? I suspect that large part comes from that they have been thrown in front of Word with very little guidance or training, because "everyone knows how to use Word", and they then just struggle on, occasionally googling and finding equally bad hints that they are unable to recognize as such because they don't know the fundamentals. Despite of its appreances Word is actually fairly complex (probably too much so for its own good) software. Another big part, especially in corporate environment, is that "templates" that people are supposed to use are almost universally horrible. Either the concrete template files are bad, or the users are given some other document and told to make theirs look the same, which typically won't end well due aforementioned reasons. Sure, Word also has true issues in this area too, but lot of the problems are cultural, and of course there is a feedback thing going on also that bad practices fester more bad practices and sort of also suppresses MS from radically improvong the situation.
  - cup-of-tea 9y ago
noer 9y ago
I've mostly switched to Dropbox Paper for writing work-related documents (and I think that product has some, "oddness", that I'd have difficulty explaining to a non-technical person). It seems to follow markdown syntax. I find it great for general writing tasks or creating documents I want to be able to refer back to, but it's probably missing some of the publishing & formatting features people get from Google Docs & Microsoft Word. I'm not a huge fan of MS Word myself, but in the limited experience I had, it's very difficult to get people to move away from it. I'm kind of feeling like this is the kind of thing that software developer see as an obvious improvement to let people know about, but miss on the fact that there isn't a huge amount of friction on the problem this solution solves.
dustinmoorenet 9y ago
I agree that Markdown is great and all but * File size. Not a big matter now-a-days but single text file can store many times more information than a binary file. I don't think the author knows what a binary file is.
- raesene9 9y ago
  and perhaps doesn't realise that .docx is just zipped XML
  - drodil 9y ago
    Ok I admit the mistaken word in the article. Still the argument is valid, don't you agree? :)
    - raesene9 9y ago
      if you'd argued that the Docx format is unecessarily verbose, well that's a possibility (Although the problem is that MS are dealing with 30 years of legacy here, it's not a simple task. One of Word's better achievements is that I can generally open 20+ year old documents and they'll render just like they did back when they were created) but to say that .docx is a binary file format, nope, it's a zipped text file format. If you parse docx you unzip and use an XML parser, you don't use a binary parser. .doc was a binary format, but that's not been a default file format for Word in the last 15 years.
codingdave 9y ago
I've spent the bulk of my career on content-driven apps, ranging from basic CMS systems to platforms that manage workflow of large, complex, legal documents. And I can tell you that while Markdown works for basic formatting of short documents, it falls short when you work with people whose entire lives revolve around long documents with complex formatting. (Attorneys, policy writers, etc.) A UX that exposes markdown to that crowd just isn't widely accepted. And that is before we even get into actual features like TOCs, headers, pagination, margin control, nested tables, etc. Now, the benefits of Markdown listed in the article are all true -- but also only loosely tied to the UX of the actual document authors and editors. If Markdown supports your formatting needs, sure, it is a good storage syntax for your content, fine. But don't make attorneys, policy writers, etc., use it. I'm not saying MS Word is the only answer either, but I highly recommend that people find/modify/create a more robust editor for your authors.
- chapium 9y ago
  One thing I noticed back in school was my law prof always kept his notes in html. When not teaching he was a local county judge. Is this common? The cases he would cover were normal city disputes and not specific to technology. I think he preferred html since it was very easy keep text in a neatly formatted hierarchy.
  - codingdave 9y ago
    Yes, I've worked on many systems where the underlying document storage was HTML. It handles the complexity needed by 90+% of the clientele I've worked with, and has all the benefits of plain-text storage -- merging, cross-platform, flexible storage, etc. And you can include attributes to handle tracking changes within a document, put it into a rendering engine that will handle your desired margins, pagination, headers, etc. Coding such a system isn't always ideal. There are a plethora of edge cases to deal with, encoding/decoding the spacial characters, and you often create lots of extra markup for advanced features. It won't win any awards for elegance. But from a purely functional perspective of does it do the job... yes, HTML works.
- Finnucane 9y ago
teilo 9y ago
If you are the only one editing your documents, and if you have a workflow that which needs nothing more than what Markdown provides, this is well and good. But in the business world, particularly legal and finance, this is rarely the case.
blunte 9y ago
I was expecting a bit more from the article, given the first thing I read at the top of the page was, "(author name) just another legendary software developer." As much as I dislike Word, you cannot simply compare Markdown to Word. Markdown is a text based format specification, while Word is a massive tool comprised of countless features (which happen to include a WYSIWYG editor).
MajorSauce 9y ago
Last time Markdown was written about on HN, someone mentionned Typora (https://typora.io/ https://typora.io/) for a very simple WYSIWYG text editing. Just wanted to share it again, as it became my favorite Markdown editor for university or sometimes work.
- ljw1001 9y ago
  This is what I want. My goto editors are Pages on the mac for heavy formatting, and Google Docs for everything else. I'd love to use Markdown more, but writing your text in one window and viewing it in another is very 1982. It just isn't good enough.
dahart 9y ago
Markdown is great, there are a bunch of really good reasons to use it. But Markdown doesn't compete with Word, really at all. There's no strong reason to frame them as opposites or to suggest that one can replace the other. Word is an editor, and Markdown is a spec. Word is wysiwyg, and Markdown is not. Word is built to handle large and complex documents with complex formatting and references, Markdown is (primarily) made for lightweight use to create simple web pages. Word is simultaneously an horrific beast and a beautiful program, but the list of features Word has that Markdown doesn't support is probably 2-3 orders of magnitude larger than the list of features Markdown even has. Word can do everything Markdown can do, but not the other way around, even if you allow for arbitrary HTML (which is cheating). I'm all for Markdown when it's appropriate, and while I try to avoid Word for simple text documents, there are absolutely times that it's called for. Definitely learn Markdown. And then use the right tool for the job.
- tzs 9y ago
  > But Markdown doesn't compete with Word, really at all. There's no strong reason to frame them as opposites or to suggest that one can replace the other. Word is an editor, and Markdown is a spec. Word is wysiwyg, and Markdown is not. I'd say the big difference between word processors (Word, LibreOffice, etc) and Markdown (or LaTeX) is that word processors are the IDEs of writing. They provide an environment and tools for not just entering your text and formatting it, but also tools for helping you create your content and manage it and work on it collaboratively. > Word is simultaneously an horrific beast and a beautiful program, but the list of features Word has that Markdown doesn't support is probably 2-3 orders of magnitude larger than the list of features Markdown even has. Word can do everything Markdown can do, but not the other way around, even if you allow for arbitrary HTML (which is cheating) The amazing thing about Word (more so in earlier editions...it's not quite as good at this currently) is that they tossed in nearly everything that any given user needs, which resulted in a bazillion features since different users need different things, but somehow managed to make it so that you can mostly ignore the features you do not need. Usually the kitchen sink approach results in a program that is totally unusable by nearly everyone.
- typon 9y ago
  Is there a document spec out there that is more feature-full than Markdown, but isn't Latex? Is it even possible to create such a spec and not end up re-creating Latex?
billfruit 9y ago
Most of the documents I write are letters which are printed and faxed/posted to people.I tried using asciidoc, but unlike latex there is no document class like letter, which automatically formats the content as required for a letter.I think markdown and similar methods needs to be further enhanced for many common documentation use cases.
geraldbauer 9y ago
Yes! Yes! Yes! Big fan of markdown and friends. At the Awesome Makrdown page [1] I try to collect all awesome goodies about Markdown. Anything missing? Contributions welcome. PS: What's wrong with markdown? Let's evolve markdown (delete, yes, delete some gimmicks, change some and add some) - see Texi - Text with Instructions [2] for the "next generation" the best of markdown and wikimedia markup all together now. [1]: https://github.com/mundimark/awesome-markdown https://github.com/mundimark/awesome-markdown [2]: https://texti.github.io https://texti.github.io
jryan49 9y ago
They are different things. You're not going to use markdown when interacting with "normal" people...
- ozim 9y ago
  I had a fellow that wanted teach sales guys to use LATEX so they could keep documents versioned in GIT... Kind of makes sense from developer perspective :) not much from sales perspective.
peterwwillis 9y ago
Markdown is not a replacement for Word. However, you should try StackEdit (https://stackedit.io/ https://stackedit.io/) if you just need a quick way to write, preview, and store Markdown files in Google Docs.
AdmiralAsshat 9y ago
I've tried to switch to Markdown almost completely for portability, but I end up having to return to Word frequently to accomplish certain features. IMO, Markdown's biggest flaw was that the original feature set was incomplete, and everyone has tried to fill in the gaps (TOC, tables, references, etc.) their own way instead of settling on an updated standard. That makes it really frustrating when I've got to rely on GitHub-flavored Markdown to accomplish something without being able to trust that it will work on a platform that only supports vanilla Markdown, etc. One thing I will give Word credit for, despite all my qualms with it, is that it's probably the only program that I can blindly paste something from my clipboard and expect that Word will render it reasonably well.
- sandworm101 9y ago
  >>> that Word will render it reasonably well. You know MS products are pretty bad when the best one expects is that content cut from another owned product renders "reasonably well". We should expect, demand, that windows clipboard integrate perfectly with Word.
  - dmh2000 9y ago
    maybe its harder than it looks
- yjftsjthsd-h 9y ago
  > it's probably the only program that I can blindly paste something from my clipboard and expect that Word will render it reasonably well. Which is funny, because going the other direction (copying from Word then pasting elsewhere) seems to guarantee _interesting_ output. Mangled quotes being the most famous example.
- jxdxbx 9y ago
  Markdown was specifically designed to just be shorthand for HTML tags--most of the missing features don't meet that criterion.
eadmund 9y ago
Even better than Markdown is Org-mode: the latter can do everything the former can do, and has every advantage other than being massively hyper-popular, and it has many, many, many other features (definition lists, scheduling, time-tracking, task-management &c. &c. ad infinitum). Yes, Markdown is an improvement over Word — and Org-mode is an improvement over Markdown (other than not being as popular).
- Grumbledour 9y ago
  I think what Org-mode really needs are plugins for other editors or maybe an editor all by itself. Of course, this will likely not happen, because people who love Org-Mode also love emacs. But having to learn and use emacs before being able to learn and use Org-mode just means it will never be really popular.
zaarn 9y ago
While using Markdown everywhere is probably a misguided but well-meant effort, I think it can be more easily agreed that Word is damaging as it basically limits the user to Windows (or having to import to LibreOffice which seems to be doing better but still blows up on seemingly simple office files) We should be trying to remove .docx and use more widely available standards that everyone can use, even if it's just LO's format.
pronoiac 9y ago
Ugh, so close... I've been working on translating a scanned PDF [1] back to Markdown, and I've stumbled on some issues: * we're kinda targeting Github Flavored Markdown, but there's also an online version which uses Docsify, and some incompatibilities have tripped me up: hard line breaks, specifically. * I've tried Mou and MacDown to edit, and the preview pane drifts out of sync, and sticks there. Both require awkward tricks to reload the files if you edit them elsewhere. * diagrams and math formulae are, well, I'm kicking the can down the road on those. * footnotes with text aren't exactly standard yet. Glancing at Dillinger and StackEdit, mentioned in the article, I see other issues: * multiple lines aren't automatically paragraphs * StackEdit sorta supports diagrams and math expressions, but, not in a way they'll render on the target. Having vented about all that, to come back to the article: this is still far preferable to Word. These obstacles don't feel insurmountable, and I was easily able to whip up tooling to go back and forth from one file for the book to a file per chapter, and it's mostly easy to track changes with git and Github. [1] PAIP, previously discussed here: https://news.ycombinator.com/item?id=16469167 https://news.ycombinator.com/item?id=16469167
ggambetta 9y ago
Couldn't agree more. I've made the switch some time ago and couldn't be happier. In fact, I wrote an entire textbook [0] and a novel [1] in Markdown (and I wrote about the markdown-to-print workflow here [2]). I still use Google Docs, but more as a distributed note-taking thing, be it docs or spreadsheets, than for "production" stuff; especially for things that benefit from being version-controlled. [0] https://github.com/ggambetta/computer-graphics-from-scratch https://github.com/ggambetta/computer-graphics-from-scratch [1] http://www.gabrielgambetta.com/the-golden-legacy.html http://www.gabrielgambetta.com/the-golden-legacy.html [2] http://www.gabrielgambetta.com/tgl_open_source.html http://www.gabrielgambetta.com/tgl_open_source.html
_dan 9y ago
I have one more: Bit-rot resistance. If you've ever tried to work on an MSWord document that's been around the houses a bit and had lots of work on it by different people (using different versions of different applications), with font choices and colours and formatting changing on a whim, you'll know they can degrade over time and become cumbersome to edit.
mcculley 9y ago
I don't understand the love for Markdown. I get that it is useful for quick and dirty formatting. But as soon as I want to make a document that can interoperate with others or has long term use requirements, I reach for XHTML. It is not sexy, but it has a well understood definition. As far as I know, Markdown still has a few different definitions that are not perfectly compatible.
kilon 9y ago
No thanks, I prefer my Libreoffice. I like markdown for simple stuff but other than that, nope.
- lproven 9y ago
  I like LibreOffice too, but it has no outliner mode. That leaves it hopelessly crippled for me, sadly. I use Calc, Impress and so on, but I write in MS Word 97 under WINE. Faster, industry-standard for right or wrong, and very very quick on 21st century hardware.
manishsharan 9y ago
MS Word is part of the interoffice workflow ; a formal word document has a predefined and deliberately inflexible template, it goes though several iterations of edits and approvals. Features like Track changes , templates and WYSIWYG enable organization to efficiently create reliable documents. Markdown is awesome but it is not an alternative to MS Word.
d3fault 9y ago
As a current high school student: hell no. I've tried writing study guides for myself in Markdown, and while it is useful, it is 10x easier to do it in Word. Plus, as many people are saying, everyone uses Word. My school even gives out Office 365 subscriptions for free.
feiss 9y ago
I think this is in front page because we nerds just want the definitive reason to say 'fuck Word' and use MD or similar. But -as we can read in these comments- there are lots of reasons and situations where this is ridiculous.
kstenerud 9y ago
No matter what format/tool you come up with, there will be use cases it doesn't support, yet are needed. When it comes to the written word, the world of legitimate, needed use cases is HUGE. The word processor is the natural evolutionary response to this need: A complex hodge podge of features and ways to visualize the content you're creating. You can tell that this article was written by an engineer because he's willing the world to fit into his neat and tidy box. It completely ignores the needs of most other industries. Were markdown to become the new standard, it wouldn't take long for a thousand ISO specs and extensions to come into being, until finally markdown is as complex as SOAP, and people go back to using Word.
throwaway2016a 9y ago
For legal documents, Statements of Work, bids, etc. I've been using latex a lot lately. It has most of the benefits of Markdown but is way more powerful. The learning curve is quite high though and to call it human readable is a stretch sometimes. I like to write common documents up front then put macros in place of things like "client name" -- then at the top of the file I declare them and it makes for really easy document generation.
ivan_ah 9y ago
For people who have Word/RTF formatted text and want to convert it to markdown, this is a very nice little utility to convert text quickly: https://puppypaste.com/ https://puppypaste.com/ I use it almost every day when copy-pasting from from shared google docs.

97 points by drodil 9y ago

deleted 9y ago

[deleted]

I want to use markdown for our technical documents. But MS Word really has some features that are missing that would be needed for a markdown editor to make a dent in what we need. 1. auto-generating table of contents 2. easy table creation/manipulation 3. header/footer and page numbering 4. comments/edits (maybe integrated with git?) It's unrealistic to expect non-technical people to learn LaTeX, so we're stuck with MS Word until someone makes an amazing Markdown editor that can handle these things.

drodil 9y ago
Very good point. There would be an awesome opportunity for some software engineer to create such editor (cross-platform of course). Also it could support other markup languages such as Textile as they don't differ from each other so much. Also what would help this is that the Markdown was standardized and would have these features included out-of-the-box.
- xienze 9y ago
  > Also what would help this is that the Markdown was standardized and would have these features included out-of-the-box. There is technically a standard Markdown dialect called CommonMark. The main problem with it is that its specification is example-driven and there's lots of places where things are up for interpretation, but for the most part it achieves its goal. What it really needs is standardization of extensions like tables, diagrams, etc.
j_4 9y ago
3. is automatically added and easy to adjust when using the Markdown PDF extension for VS Code.[1] [1]: https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf https://marketplace.visualstudio.com/items?itemName=yzane.ma...
oneeyedpigeon 9y ago
Well, markdown files are just plain text, so you get the git integration 'for free'. As for 2&3, this is why I author documents in HTML: about the same level of complexity as MD, but far, far more powerful. 1, I'll give you, is an issue, just one I don't even run into (I tend not to be editing documents so huge that they demand a ToC).
- geogra4 9y ago
  We do a lot of large design/spec documents so we really make a lot of use of that.
  - oneeyedpigeon 9y ago
    I think if I had that use-case, I would consider writing a small piece of javascript to generate the ToC. Maybe even possible with CSS, although it could well be too hack-ish for that approach.
cup-of-tea 9y ago
Org-mode can do all of those things.
- geogra4 9y ago
  Emacs is going to be just as obtuse for your everyday business analyst as LaTeX
  - eadmund 9y ago
    The original emacs paper[0] noted that many of the users who started programming were secretaries who didn't know that they could. Learning how to truly use a computer is as important in the 21st century as learning to read was in the 19th: those who find emacs obtuse need to learn it just as certainly as those who found letters confusing. [0] https://www.gnu.org/software/emacs/emacs-paper.html#SEC29 https://www.gnu.org/software/emacs/emacs-paper.html#SEC29
    - cup-of-tea 9y ago
      Yes, it is unfortunate that so many use computer-shaped devices but only a very small number actually do computing. The rise of point-and-click has done a really good job of hiding the possibilities from people. Eben Moglen likened point-and-click to a "caveman interface" where your only options are pointing and grunting, as opposed to using language to communicate your ideas. Only programmers do the latter but that is a shame.
      - deckard1 9y ago
        > Only programmers do the latter but that is a shame. Part of me says this is job security for software developers. The other part of me saw non-programmers try to use Excel as a layout/desktop publishing/vector graphics tool. But seriously, if you know how to program and you do literally anything else, then you become a developer. It's the cushiest job with the highest pay. The other reason it will never happen is because the developer's job isn't to make the office worker more efficient (that's Microsoft's job, so I suppose some developer does it, just not all developers). The developer's job is to increase efficiency. Either internal efficiency, or external efficiency. And that means: jobs will be lost. Rather than training office workers how to program and have them leave for a developer job, it's better to just pay developers and have them automate an entire class of office workers' jobs. Hopefully all developers get the opportunity to witness internal efficiency planning. Most developers are disconnected from the process. But to actually meet the people you're going to eliminate with software in a month or two is truly something.
adzicg 9y ago
"pandoc --toc" puts a TOC in when creating pdf files. You can also use "--toc-depth=XXX" to select how many levels of headings you want in the toc. page numbers also get added automatically I think when using the book docclass.
lloeki 9y ago
Our needs are simple, so we have something† based on kramdown (in GFM mode) and tilt-pdf[0] (shameless plug) which generates a TOC, handles styles, headers/footers, and leverages wkhtmltopdf††. Documentation is in git as markdown files, linted, generated, and published as part of CI/CD. Comments/edits are done though GitLab MRs implementing an editorial review process. Occasional contributions are done through GitLab web editor, and more involved non-technical people use VSCode to sync, write, and commit. The GitLab flow of (Issue->Branch->MR)->(Fetch->Edit->Commit->Push)->(Review->Merge->Publish) is quite assisted and works quite well with open-minded non-tech people. [0]: https://github.com/lloeki/tilt-pdf https://github.com/lloeki/tilt-pdf † The tool should be open-sourced as soon as we can clean up the code of hardcoded internal stuff. It'll appear over there: https://github.com/adhoc-gti/makebook https://github.com/adhoc-gti/makebook †† Contemplating moving to headless Chrome. Also, increasingly using Hugo for online documentation.
- geogra4 9y ago
  This looks really neat! I'd love to experiment with this
- pzb 9y ago
  I've been working on a similar system that is in the process of being adopted by at least one standards group (https://github.com/cabforum/documents https://github.com/cabforum/documents ). I would strongly recommend looking at weasyprint (http://weasyprint.org/ http://weasyprint.org/ ) for HTML to PDF. It gives much better PDF output and offers CSS print support, so you get page control.
shadowfiend 9y ago
asciidoc via asciidoctor (https://asciidoctor.org https://asciidoctor.org) covers a lot of this, though not bundled into a system. Comments/edits via something like GitHub, tables (https://asciidoctor.org/docs/user-manual/#tables https://asciidoctor.org/docs/user-manual/#tables), tables of contents (https://asciidoctor.org/docs/user-manual/#user-toc https://asciidoctor.org/docs/user-manual/#user-toc), and with some docbook work (admittedly annoying), you can get header/footer and page number (https://asciidoctor.org/docs/user-manual/#docinfo-file https://asciidoctor.org/docs/user-manual/#docinfo-file). It's not perfect, but it's very similar in concept to Markdown, has several adaptations to make the md->adoc transition easier, and is much more feature-rich, thanks to being based on Docbook (which is used for creating much more complicated documents than Markdown historically has been).
- castillar76 9y ago
  Agreed. As someone that manages multiple documents under heavy revision control in a public repository (yay, public certificate authority documentation), Asciidoc has been a life-saver. We used Word for a long time, but found it was way too difficult to track revisions and approvals using it. Inevitably, you'd pass the document to eight people that need to approve and get back eight sets of changes, which you then have to integrate in and hope no one has introduced a regression from "DOCUMENT_JONREVIEW_VERSION1_COMMENTS_FINAL_FINAL_DRAFT_FINAL_DRAFT_FINAL_COMMENTS_V6". Moreover, the people doing the reviews are a mix of technical and non-technical, and doing the review/approval process in Word docs meant constructing an Alfresco instance or similar to track the approvals and validate for auditors that we'd completed reviews before pushing updates. Also, you have to create something to keep track of the Word document originals /and/ the PDFs they produce—it always seemed like the Word originals would disappear at some point, leaving everyone to back-create them from the PDFs. Now we do the documents in AsciiDoc, and track everything in an internal Github repository using pull requests. The diffs are clean and are actually easier to read: you can comment, you can immediately see where the changes are, and everyone is focused on changes in content rather than getting distracted by font and spacing choices. Once N people out of M have approved the pull request, I can merge it into the master and then publish it into a clean, readable PDF with an auto-generated table of contents, page numbers, footers, and the like. Now, if someone were to invent a WYSIWYG app for Asciidoc, that would be awesome, but this seems to be working a whole heck of a lot better than the previous Word-based method.

donquichotte 9y ago

Ooooh man, I would love to do that. I enjoy writing markdown, and I enjoy using pandoc. However, whenever I have to print something, there is pretty much just one possibility in Markdown: export as pdf. And export as pdf uses Latex. Latex is cool. But if you want to customize your document, you will sooner or later need to include latex headers into the "build" process of your file, and soon you have a clusterfuck of tooling and a make file for a document that was supposed to be a simple report. And then I'd rather write it in Latex. Does anybody have a solution for this? Some kind of print-friendly Markdown-to-PDF workflow? All the non-Latex alternatives looked horrible. In fact, I sometimes export markdown documents to Word just to print them.

xienze 9y ago
MD->HTML->PDF. Just use a browser to render your document. You can make the process a bit more automated by using something like Chrome Headless. I'm sure there's a project out there that does this all in one step from the commandline.
- donquichotte 9y ago
  This approach is what I have sometimes been using. It works OK and I can style my documents with CSS. But there are little things that bug me, like headlines on the last line of page N and the paragraph starting on page N+1 and header/footer lines generated by the browser.
  - laxis 9y ago
    for what it's worth you can define pagebreaks with css [0]. it's not the most user-friendly way, but works. the @page rule also comes in quite handy [0]: https://developer.mozilla.org/en-US/docs/Web/CSS/page-break-inside https://developer.mozilla.org/en-US/docs/Web/CSS/page-break-...
- nathan_long 9y ago
  My setup: 1) I have cmark installed 2) https://github.com/nathanl/.dotfiles/blob/master/bin/md_preview https://github.com/nathanl/.dotfiles/blob/master/bin/md_prev... is a script to render STDIN to HTML and slap the output into the middle of a template that has some basic CSS (https://github.com/nathanl/.dotfiles/blob/master/bin/md_preview_template.html https://github.com/nathanl/.dotfiles/blob/master/bin/md_prev...) 3) I write markdown in Vim and use keybindings to say "now output HTML from this buffer" - https://github.com/nathanl/.dotfiles/blob/ede8c98a7897ee07b724b4225c2ac3a765341c25/vim/vimrc#L299-L302 https://github.com/nathanl/.dotfiles/blob/ede8c98a7897ee07b7... I like this mainly because it lets me use Vim, which for me is the most efficient tool for wrangling text. I also like avoiding WISYWIG programs that I previously fought with - eg, trying to get Word to understand which bullet points I wanted nested under which other ones was frustrating, but with markdown (and embedded HTML when necessary) I can be 100% explicit. Sometimes I copy-paste the resulting HTML into Google Docs or elsewhere and do further tweaks, but most of the time it's enough for me as-is.

Proven 9y ago

Bullshit. Word is a nice editor and can edit Markdown files too. There’s also a free add-on that makes it easier to handle the MD format.

cup-of-tea 9y ago

Right now I'm writing a document in plain text. Not markdown but org-mode. I could export it as markdown for collaboration purposes easily enough. What I will get at the end is a higher quality document than most Word users will produce but with a minimal amount of effort. The thing is a document only really contains a handful of different elements. Therefore you only need a handful of styles. What you do is make a template document for pandoc in the format of your choice (e.g. MS Word) and then your markdown/org-mode document can be automatically converted into that style. The problem with Word is it makes choosing ad-hoc styles really easy instead of promoting the use of styles. It has developed a culture of people who think about text being "bold" rather than text being "a heading" or "emphasised" etc. We teach this distinctionfor HTML and CSS (and it is, to some extent, used) but for some reason still use Word for writing documents.

zokier 9y ago
Styles have been best practice in Word too for decades. And in current versions the styles portion is like half of the default "home" ribbon, with big buttons and fancy live previews and all, so you can't really argue that they would be especially hidden in the UI. Still, it is true that your average Word user still typically produces fairly horrible documents. Why is that? I suspect that large part comes from that they have been thrown in front of Word with very little guidance or training, because "everyone knows how to use Word", and they then just struggle on, occasionally googling and finding equally bad hints that they are unable to recognize as such because they don't know the fundamentals. Despite of its appreances Word is actually fairly complex (probably too much so for its own good) software. Another big part, especially in corporate environment, is that "templates" that people are supposed to use are almost universally horrible. Either the concrete template files are bad, or the users are given some other document and told to make theirs look the same, which typically won't end well due aforementioned reasons. Sure, Word also has true issues in this area too, but lot of the problems are cultural, and of course there is a feedback thing going on also that bad practices fester more bad practices and sort of also suppresses MS from radically improvong the situation.
- cup-of-tea 9y ago

noer 9y ago

I've mostly switched to Dropbox Paper for writing work-related documents (and I think that product has some, "oddness", that I'd have difficulty explaining to a non-technical person). It seems to follow markdown syntax. I find it great for general writing tasks or creating documents I want to be able to refer back to, but it's probably missing some of the publishing & formatting features people get from Google Docs & Microsoft Word. I'm not a huge fan of MS Word myself, but in the limited experience I had, it's very difficult to get people to move away from it. I'm kind of feeling like this is the kind of thing that software developer see as an obvious improvement to let people know about, but miss on the fact that there isn't a huge amount of friction on the problem this solution solves.

dustinmoorenet 9y ago

I agree that Markdown is great and all but * File size. Not a big matter now-a-days but single text file can store many times more information than a binary file. I don't think the author knows what a binary file is.

raesene9 9y ago
and perhaps doesn't realise that .docx is just zipped XML
- drodil 9y ago
  Ok I admit the mistaken word in the article. Still the argument is valid, don't you agree? :)
  - raesene9 9y ago
    if you'd argued that the Docx format is unecessarily verbose, well that's a possibility (Although the problem is that MS are dealing with 30 years of legacy here, it's not a simple task. One of Word's better achievements is that I can generally open 20+ year old documents and they'll render just like they did back when they were created) but to say that .docx is a binary file format, nope, it's a zipped text file format. If you parse docx you unzip and use an XML parser, you don't use a binary parser. .doc was a binary format, but that's not been a default file format for Word in the last 15 years.

codingdave 9y ago

I've spent the bulk of my career on content-driven apps, ranging from basic CMS systems to platforms that manage workflow of large, complex, legal documents. And I can tell you that while Markdown works for basic formatting of short documents, it falls short when you work with people whose entire lives revolve around long documents with complex formatting. (Attorneys, policy writers, etc.) A UX that exposes markdown to that crowd just isn't widely accepted. And that is before we even get into actual features like TOCs, headers, pagination, margin control, nested tables, etc. Now, the benefits of Markdown listed in the article are all true -- but also only loosely tied to the UX of the actual document authors and editors. If Markdown supports your formatting needs, sure, it is a good storage syntax for your content, fine. But don't make attorneys, policy writers, etc., use it. I'm not saying MS Word is the only answer either, but I highly recommend that people find/modify/create a more robust editor for your authors.

chapium 9y ago
One thing I noticed back in school was my law prof always kept his notes in html. When not teaching he was a local county judge. Is this common? The cases he would cover were normal city disputes and not specific to technology. I think he preferred html since it was very easy keep text in a neatly formatted hierarchy.
- codingdave 9y ago
  Yes, I've worked on many systems where the underlying document storage was HTML. It handles the complexity needed by 90+% of the clientele I've worked with, and has all the benefits of plain-text storage -- merging, cross-platform, flexible storage, etc. And you can include attributes to handle tracking changes within a document, put it into a rendering engine that will handle your desired margins, pagination, headers, etc. Coding such a system isn't always ideal. There are a plethora of edge cases to deal with, encoding/decoding the spacial characters, and you often create lots of extra markup for advanced features. It won't win any awards for elegance. But from a purely functional perspective of does it do the job... yes, HTML works.
Finnucane 9y ago

teilo 9y ago

If you are the only one editing your documents, and if you have a workflow that which needs nothing more than what Markdown provides, this is well and good. But in the business world, particularly legal and finance, this is rarely the case.

blunte 9y ago

I was expecting a bit more from the article, given the first thing I read at the top of the page was, "(author name) just another legendary software developer." As much as I dislike Word, you cannot simply compare Markdown to Word. Markdown is a text based format specification, while Word is a massive tool comprised of countless features (which happen to include a WYSIWYG editor).

MajorSauce 9y ago

Last time Markdown was written about on HN, someone mentionned Typora (https://typora.io/ https://typora.io/) for a very simple WYSIWYG text editing. Just wanted to share it again, as it became my favorite Markdown editor for university or sometimes work.

ljw1001 9y ago
This is what I want. My goto editors are Pages on the mac for heavy formatting, and Google Docs for everything else. I'd love to use Markdown more, but writing your text in one window and viewing it in another is very 1982. It just isn't good enough.

dahart 9y ago

Markdown is great, there are a bunch of really good reasons to use it. But Markdown doesn't compete with Word, really at all. There's no strong reason to frame them as opposites or to suggest that one can replace the other. Word is an editor, and Markdown is a spec. Word is wysiwyg, and Markdown is not. Word is built to handle large and complex documents with complex formatting and references, Markdown is (primarily) made for lightweight use to create simple web pages. Word is simultaneously an horrific beast and a beautiful program, but the list of features Word has that Markdown doesn't support is probably 2-3 orders of magnitude larger than the list of features Markdown even has. Word can do everything Markdown can do, but not the other way around, even if you allow for arbitrary HTML (which is cheating). I'm all for Markdown when it's appropriate, and while I try to avoid Word for simple text documents, there are absolutely times that it's called for. Definitely learn Markdown. And then use the right tool for the job.

tzs 9y ago
> But Markdown doesn't compete with Word, really at all. There's no strong reason to frame them as opposites or to suggest that one can replace the other. Word is an editor, and Markdown is a spec. Word is wysiwyg, and Markdown is not. I'd say the big difference between word processors (Word, LibreOffice, etc) and Markdown (or LaTeX) is that word processors are the IDEs of writing. They provide an environment and tools for not just entering your text and formatting it, but also tools for helping you create your content and manage it and work on it collaboratively. > Word is simultaneously an horrific beast and a beautiful program, but the list of features Word has that Markdown doesn't support is probably 2-3 orders of magnitude larger than the list of features Markdown even has. Word can do everything Markdown can do, but not the other way around, even if you allow for arbitrary HTML (which is cheating) The amazing thing about Word (more so in earlier editions...it's not quite as good at this currently) is that they tossed in nearly everything that any given user needs, which resulted in a bazillion features since different users need different things, but somehow managed to make it so that you can mostly ignore the features you do not need. Usually the kitchen sink approach results in a program that is totally unusable by nearly everyone.
typon 9y ago
Is there a document spec out there that is more feature-full than Markdown, but isn't Latex? Is it even possible to create such a spec and not end up re-creating Latex?

billfruit 9y ago

Most of the documents I write are letters which are printed and faxed/posted to people.I tried using asciidoc, but unlike latex there is no document class like letter, which automatically formats the content as required for a letter.I think markdown and similar methods needs to be further enhanced for many common documentation use cases.

geraldbauer 9y ago

Yes! Yes! Yes! Big fan of markdown and friends. At the Awesome Makrdown page [1] I try to collect all awesome goodies about Markdown. Anything missing? Contributions welcome. PS: What's wrong with markdown? Let's evolve markdown (delete, yes, delete some gimmicks, change some and add some) - see Texi - Text with Instructions [2] for the "next generation" the best of markdown and wikimedia markup all together now. [1]: https://github.com/mundimark/awesome-markdown https://github.com/mundimark/awesome-markdown [2]: https://texti.github.io https://texti.github.io

jryan49 9y ago

They are different things. You're not going to use markdown when interacting with "normal" people...

ozim 9y ago
I had a fellow that wanted teach sales guys to use LATEX so they could keep documents versioned in GIT... Kind of makes sense from developer perspective :) not much from sales perspective.

peterwwillis 9y ago

Markdown is not a replacement for Word. However, you should try StackEdit (https://stackedit.io/ https://stackedit.io/) if you just need a quick way to write, preview, and store Markdown files in Google Docs.

AdmiralAsshat 9y ago

I've tried to switch to Markdown almost completely for portability, but I end up having to return to Word frequently to accomplish certain features. IMO, Markdown's biggest flaw was that the original feature set was incomplete, and everyone has tried to fill in the gaps (TOC, tables, references, etc.) their own way instead of settling on an updated standard. That makes it really frustrating when I've got to rely on GitHub-flavored Markdown to accomplish something without being able to trust that it will work on a platform that only supports vanilla Markdown, etc. One thing I will give Word credit for, despite all my qualms with it, is that it's probably the only program that I can blindly paste something from my clipboard and expect that Word will render it reasonably well.

sandworm101 9y ago
>>> that Word will render it reasonably well. You know MS products are pretty bad when the best one expects is that content cut from another owned product renders "reasonably well". We should expect, demand, that windows clipboard integrate perfectly with Word.
- dmh2000 9y ago
  maybe its harder than it looks
yjftsjthsd-h 9y ago
> it's probably the only program that I can blindly paste something from my clipboard and expect that Word will render it reasonably well. Which is funny, because going the other direction (copying from Word then pasting elsewhere) seems to guarantee _interesting_ output. Mangled quotes being the most famous example.
jxdxbx 9y ago
Markdown was specifically designed to just be shorthand for HTML tags--most of the missing features don't meet that criterion.

eadmund 9y ago

Even better than Markdown is Org-mode: the latter can do everything the former can do, and has every advantage other than being massively hyper-popular, and it has many, many, many other features (definition lists, scheduling, time-tracking, task-management &c. &c. ad infinitum). Yes, Markdown is an improvement over Word — and Org-mode is an improvement over Markdown (other than not being as popular).

Grumbledour 9y ago
I think what Org-mode really needs are plugins for other editors or maybe an editor all by itself. Of course, this will likely not happen, because people who love Org-Mode also love emacs. But having to learn and use emacs before being able to learn and use Org-mode just means it will never be really popular.

zaarn 9y ago

While using Markdown everywhere is probably a misguided but well-meant effort, I think it can be more easily agreed that Word is damaging as it basically limits the user to Windows (or having to import to LibreOffice which seems to be doing better but still blows up on seemingly simple office files) We should be trying to remove .docx and use more widely available standards that everyone can use, even if it's just LO's format.

pronoiac 9y ago

Ugh, so close... I've been working on translating a scanned PDF [1] back to Markdown, and I've stumbled on some issues: * we're kinda targeting Github Flavored Markdown, but there's also an online version which uses Docsify, and some incompatibilities have tripped me up: hard line breaks, specifically. * I've tried Mou and MacDown to edit, and the preview pane drifts out of sync, and sticks there. Both require awkward tricks to reload the files if you edit them elsewhere. * diagrams and math formulae are, well, I'm kicking the can down the road on those. * footnotes with text aren't exactly standard yet. Glancing at Dillinger and StackEdit, mentioned in the article, I see other issues: * multiple lines aren't automatically paragraphs * StackEdit sorta supports diagrams and math expressions, but, not in a way they'll render on the target. Having vented about all that, to come back to the article: this is still far preferable to Word. These obstacles don't feel insurmountable, and I was easily able to whip up tooling to go back and forth from one file for the book to a file per chapter, and it's mostly easy to track changes with git and Github. [1] PAIP, previously discussed here: https://news.ycombinator.com/item?id=16469167 https://news.ycombinator.com/item?id=16469167

ggambetta 9y ago

Couldn't agree more. I've made the switch some time ago and couldn't be happier. In fact, I wrote an entire textbook [0] and a novel [1] in Markdown (and I wrote about the markdown-to-print workflow here [2]). I still use Google Docs, but more as a distributed note-taking thing, be it docs or spreadsheets, than for "production" stuff; especially for things that benefit from being version-controlled. [0] https://github.com/ggambetta/computer-graphics-from-scratch https://github.com/ggambetta/computer-graphics-from-scratch [1] http://www.gabrielgambetta.com/the-golden-legacy.html http://www.gabrielgambetta.com/the-golden-legacy.html [2] http://www.gabrielgambetta.com/tgl_open_source.html http://www.gabrielgambetta.com/tgl_open_source.html

_dan 9y ago

I have one more: Bit-rot resistance. If you've ever tried to work on an MSWord document that's been around the houses a bit and had lots of work on it by different people (using different versions of different applications), with font choices and colours and formatting changing on a whim, you'll know they can degrade over time and become cumbersome to edit.

mcculley 9y ago

I don't understand the love for Markdown. I get that it is useful for quick and dirty formatting. But as soon as I want to make a document that can interoperate with others or has long term use requirements, I reach for XHTML. It is not sexy, but it has a well understood definition. As far as I know, Markdown still has a few different definitions that are not perfectly compatible.

kilon 9y ago

No thanks, I prefer my Libreoffice. I like markdown for simple stuff but other than that, nope.

lproven 9y ago
I like LibreOffice too, but it has no outliner mode. That leaves it hopelessly crippled for me, sadly. I use Calc, Impress and so on, but I write in MS Word 97 under WINE. Faster, industry-standard for right or wrong, and very very quick on 21st century hardware.

manishsharan 9y ago

MS Word is part of the interoffice workflow ; a formal word document has a predefined and deliberately inflexible template, it goes though several iterations of edits and approvals. Features like Track changes , templates and WYSIWYG enable organization to efficiently create reliable documents. Markdown is awesome but it is not an alternative to MS Word.

d3fault 9y ago

As a current high school student: hell no. I've tried writing study guides for myself in Markdown, and while it is useful, it is 10x easier to do it in Word. Plus, as many people are saying, everyone uses Word. My school even gives out Office 365 subscriptions for free.

feiss 9y ago

I think this is in front page because we nerds just want the definitive reason to say 'fuck Word' and use MD or similar. But -as we can read in these comments- there are lots of reasons and situations where this is ridiculous.

kstenerud 9y ago

No matter what format/tool you come up with, there will be use cases it doesn't support, yet are needed. When it comes to the written word, the world of legitimate, needed use cases is HUGE. The word processor is the natural evolutionary response to this need: A complex hodge podge of features and ways to visualize the content you're creating. You can tell that this article was written by an engineer because he's willing the world to fit into his neat and tidy box. It completely ignores the needs of most other industries. Were markdown to become the new standard, it wouldn't take long for a thousand ISO specs and extensions to come into being, until finally markdown is as complex as SOAP, and people go back to using Word.

throwaway2016a 9y ago

For legal documents, Statements of Work, bids, etc. I've been using latex a lot lately. It has most of the benefits of Markdown but is way more powerful. The learning curve is quite high though and to call it human readable is a stretch sometimes. I like to write common documents up front then put macros in place of things like "client name" -- then at the top of the file I declare them and it makes for really easy document generation.

ivan_ah 9y ago

For people who have Word/RTF formatted text and want to convert it to markdown, this is a very nice little utility to convert text quickly: https://puppypaste.com/ https://puppypaste.com/ I use it almost every day when copy-pasting from from shared google docs.