
Say Yes to Markdown, No to MS Word - drodil
https://medium.com/@drodil/say-yes-to-markdown-no-to-ms-word-be4692e7a8cd
======
codingdave
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.

~~~
rayiner
As someone who wrote his school papers LaTeX and now jockeys Word for a living
as an attorney, let me tell you why Word is awesome:

1) Everyone uses it. You get documents from co-counsel, and you can flip on
track changes and send some comments. Track changes is better than version
control (for legal documents). Word shows you what you just deleted, so you
can be sure you haven't changed the meaning without intending to. And co-
counsel doesn't use git so sending diffs around is of limited utility.

2) Typesetting is built-in. Yes, this is one thing that's terrible about Word
and great about LaTeX. Separation of content and presentation is good. Except
when it's not. Word is, for the most part, WYSIWYG. That means I can tweak my
hyphenation or kerning as I go, and when I print to PDF 5 minutes before the
brief is due to the printer (as in dead trees), I can be pretty sure what
it'll look like. LaTeX lets you control that too, but the "production" step is
often longer.

3) Speaking of formatting: legal documents, and often other business
documents, aren't just mechanical. For something like an appellate brief in an
important case, thousands of people might read it (and its enshrined immutable
in the public record for posterity). The content is the most important thing,
but they also have to _look nice_. Markdown, as far as I can tell, gives you
very little control over typesetting.

Word is, from an intellectual perspective, a mish-mash of awful ideas. But
it's a really good tool for quickly producing documents that are bear a
passable resemblance to a properly typeset book page. (Which is the gold
standard--briefs for the Supreme Court until very recently were often typeset
using a hot-metal press.)

~~~
reificator
I didn't know Word had settings to adjust keming.

To be honest I only use Word to view requirements docs. I thought keming was
on a per-font basis and that's it. But if Word lets you tweak it that's pretty
cool.

~~~
teddyh
It’s “kerning”, not “keming”.

~~~
reificator
Almost like I typed it with bad keming, huh?

[http://www.ironicsans.com/2008/02/idea_a_new_typography_term...](http://www.ironicsans.com/2008/02/idea_a_new_typography_term.html)

~~~
teddyh
So I don’t recognize someone’s made-up term consisting of a cute misspelling;
I try to be helpful and point out the correct spelling, and what do I get?
Downvotes. Sigh.

~~~
reificator
I upvoted you, but remember that talking about _fight club_ will get you
_fight clubbed_.

It not just a misspelling, it's a relevant misspelling to the meaning of the
word.

------
dahart
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.

~~~
typon
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?

~~~
WorldMaker
Asciidoc and restructuredText both have more features, stronger specifications
[1].

reStructuredText has strong official support for extensions, including regular
syntaxes in the language for using extension points consistently. That power
alone makes it suitable for a lot of domain-specific documents, which is why
IMNSHO a lot of the better software documentation is in reStructuredText
rather than Markdown.

[1] Don't forget that for Markdown the only "official" spec for that name is a
blog post and a Perl script. CommonMark is very well specified now, but is A)
surprisingly quite recent despite the proliferation of Markdown usage, and B)
technically a forked specification and "not official" and not allowed to use
the name "Markdown" by the original author/developer.

~~~
bb88
The one advantage I saw over markdown vs rsT, say, was that documents with
markdown looked good when viewed in Vim as well.

But when I'm including code in a doc I much rather prefer rsT, because I can
specify the code type so the syntax highlighter doesn't have to guess about
the language.

~~~
WorldMaker
There are Vim syntax highlight scripts for rST, but they've never been
included in the base install like Markdown.

This is the one I used for years, I believe:

[https://www.vim.org/scripts/script.php?script_id=973](https://www.vim.org/scripts/script.php?script_id=973)

Looks like several people recommend this script:

[https://github.com/dhabyx/riv.vim](https://github.com/dhabyx/riv.vim)

------
AdmiralAsshat
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
>>> 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
maybe its harder than it looks

------
donquichotte
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
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
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
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-...](https://developer.mozilla.org/en-US/docs/Web/CSS/page-break-inside)

------
geogra4
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.

~~~
lloeki
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.

~~~
pzb
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.

------
MajorSauce
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
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.

------
kstenerud
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.

------
geraldbauer
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)

------
blunte
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).

------
cup-of-tea
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
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
> 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

Yes, I would agree with this. Even worse is that typing is also an expected
skill but very few people can actually do it. Almost every person I come
across for whom typing should be a necessary part of their job are simply
incapable of doing it. How can we expect people to use software like Word if
they can't even type?

But I really do think that in the vast majority of cases people do not need to
be using Word. It could very well be done in a plain text format and the
documents would look better as a result. Much of Word's functionality is very
much a "could" rather than a "should".

------
ggambetta
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)

------
peterwwillis
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.

------
dustinmoorenet
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
and perhaps doesn't realise that .docx is just zipped XML

~~~
drodil
Ok I admit the mistaken word in the article. Still the argument is valid,
don't you agree? :)

~~~
raesene9
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.

------
pronoiac
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)

------
mcculley
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.

------
_dan
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.

------
billfruit
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.

------
manishsharan
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.

------
noer
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.

------
d3fault
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.

------
zaarn
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.

------
throwaway2016a
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
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.

------
teilo
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.

------
feiss
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.

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

~~~
ozim
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.

------
eadmund
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
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.

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

~~~
lproven
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.

