Say Yes to Markdown, No to MS Word | Hacker News Reader

Say Yes to Markdown, No to MS Word

medium.com

97 pointsdrodil109 comments

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.

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.

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.

Many years ago I managed book production for a legal publisher, and in those days FrameMaker was the practically the only tool available that could really manage the task properly. If Adobe hadn't killed the Mac and Unix versions, I'd probably still be using it today.

Ah, FrameMaker, you just brought back memories for me. FrameMaker was truly awesome, I miss it. I wrote the first chapter of my thesis in Word, LaTeX and FrameMaker simultaneously to figure out which one I wanted to write the rest with. FrameMaker was more manageable by far, and supported LaTeX equations.

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

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.

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

Almost like I typed it with bad keming, huh?

http://www.ironicsans.com/2008/02/idea_a_new_typography_term...

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.

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.

Ironically enough the font+point used for HN has kind of bad kerning on the rn pair that makes it look a lot like m in comments.

I do this too, it's an ironic word that resembles its meaning. Like a textual onomatopoeia.

Parallel might be another example - are there others?

Your reply finally gave me a reason to register a user account. You had me trying to remove a non-existent smudge from my screen for nearly a minute.

I'm not going to lie, most of my reason for wanting to post was to type the word "keming".

Welcome to the comments!

Madoko combines LaTeX and Markdown, has git on the backend for diff tracking, and is built into a web frontend. http://madoko.org/reference.html

I think all of your issues with markdown can be solved with a stylesheet.

Also, I would challenge your idea that the changes tracking feature is even remotely comparable to real revision control.

"Everyone uses it" is the best argument.

>and its enshrined immutable in the public record //

I know you file a document, but the public record is the content, and increasingly access to content is not done in the form the content was originally created.

In my opinion it shouldn't "look nice" but should comply with a standardised format (which hopefully has reasonable aesthetic qualities) which was developed by an field-experienced document design specialist.

There is a standardized format: it's called PDF. Everything else is total crap. (And legal technology that doesn't grok PDF is by consequence total crap.) Everything else doesn't do what a universal standardized legal document format needs to do. Legal information systems have to be able to handle everything from briefs prepared by attorneys, to copies of documents that only ever existed in hardcopy, such as wills, birth certificates, etc., to scanned-in copies of pleadings filed on paper by tenants getting kicked out of their apartments. PDF handles this all marvelously, and Word integrates reasonably well with PDF.

PDF is just about the worst choice here. It represents a piece of paper conceptually and not the actual content.

PDF is a presentation format, not a content format.

As explained above, the separation of content and presentation is conceptually desirable, but not at the expense of being able to capture all the content you need to capture. What other format lets you capture everything from a prisoner’s pro se habeas petition (scrawled with pencil in a prison library) to legal briefs from Fortune 500 corporations?

If I were designing a court document system from scratch, I’d still use PDF, and not for lack of imagination. It’s incredibly powerful technology. I actually ran into this while looking for comprehensive note taking solutions for my legal practice. A lot of modern web-based tools don’t embrace PDF, and they’re toys as a result. I can’t scrawl notes on a deposition transcript? I have to handle key evidentiary documents as second-class attachments? Useless. I settled on an iPad Pro (great PDF markup support) and emailing myself files to my Exchange account.

My 2 cents (and from the perspective of someone who has not used Word in ages and who tends to largely prefer typing commands to clicking icons).

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

Not everyone. I do not, like many others. First, it's expensive; second, it's not 100% available. It came very late to the www world. Moreover, it might be a good tool for legal writing, but it is horrid for code typesetting or for maintaining a bibliography. Finally, it handles very badly very large documents.

On the versioning side, one thing I loved about Latex was the ability to comment and uncomment entire sections of the documents, which is AFAIK absent in Word.

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

Why would you make manual tweaks to the typesetting? This sounds like a nightmare when you have to maintain many of these manual typesetting hacks. I remember I spend a lot of time skimming long documents to check that a new line didn't break the document a few pages later.

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

To my knowledge PDFs generated by markdown are pretty decent. Maybe they are a bit boring and they all look alike, but I can't say they are ugly. But, again, this only is a personal opinion.

My personal idea is that Word is a bad software on which people who can't really use computers created suboptimal processes. Of course, we (the developers community) can't really expect that one is capable of writing his own css to have a nice typesetting or to mentally parse formatting tags to image what the output might be.

2 & 3, though, are encouraging inefficiency, not awesomeness.

The practice of high-end law is, to an unreasonable degree, about typesetting and formatting. You pay your lawyers to sweat the local judges’ preferences for margins and Arabic numerals; I’ve seen five lawyers quibbling about curly quotes and footnote placement. And the law says the lawyer is, ultimately, responsible for getting this right - the typesetting part of the brief is the practice of law, just as much as developing the legal argument.

As much as possible, I do my drafting in markdown, to separate content from typesetting. If I don’t, I find typesetting can eat up an unreasonable proportion of the overall time.

But the sooner the courts figure out a way to format the lawyers’ text according to the courts’ own preference(s), the better. Style sheets aren’t quite there, but we’re close.

In federal court, at least, it's hard to go wrong with 12-point times new roman for district court, 14-point for courts of appeal, and 1-inch margins. Supreme Court is Century font and booklet-format margins. In practice, you need to just develop a handful of Word templates.

As to the other stuff, polish and consistency are more important. In my opinion, there's a good reason why courts place so much weight on that. Judges are in a weird spot--they need to sweat the details, but don't have the time to put every brief under a microscope. So they need to trust you, but develop heuristics to decide when they can't trust you. The big one is misquoting things. If the judge notices a couple of instances where you say a case says one thing, but the case says something else, your brief will get put under a microscope. Polish is another heuristic. If you can't be bothered to spend the relatively small amount of time it takes to make sure your footnotes are formatted consistently, why should the judge assume that you've thoroughly researched the law and the record and that she can trust that it says what you say it says?

Of course, like most heuristics, it's a statistical inference rather than a logical one--like holding it against someone for showing up late to an interview. They could be reliable, but it's reasonable to think they might not be.

> Judges are in a weird spot--they need to sweat the details, but don't have the time to put every brief under a microscope.

Akin to the brown-M&Ms clause in the Van Halen contract technical appendix [0].

[0] https://www.snopes.com/fact-check/brown-out/

Well, "hard to go wrong" except when it's wrong.

California central district wants 14 points, with line numbers. Arizona district wants 13 points, no line numbers. The 7th Circuit's typography recommendations say Times New Roman might as well be Comic Sans. The Supreme Court italicizes case names differently. Massachusetts state court wants 1.5" margins on two sides. Wisconsin wants 1.5" on just the left.

Templates help, as does Butterick's Typography for Lawyers, and a good checklist. But it's still a slog to internalize all the local customs in a multi-state practice.

And yes, these are heuristics to identify locals and repeat players, which might be helpful to courts. But, again, that's a separate skill from legal reasoning, and it comes at a high cost for clients.

90% of the time, you just apply tweaks to a template you already have. Then you reuse that template in what might be dozens of filings in a case.

> Everyone uses it.

Not everyone uses Word. It doesn't run on Linux.

Word might be useful for legal docs or other specific purposes, but I wouldn't assume that everyone will be able to use all of the functionality in a Word doc.

There exists a free online version of Word: https://office.live.com/start/Word.aspx

Actually, yes it does.

For journo stuff, hypothetical deity help me, MS Word is my editor of choice. Mainly for the outliner -- it's the _only_ mainstream wordprocessor that still includes outline mode, which I find indispensable.

I mainly use Word 97 -- not the rest of Office, just a standalone copy of Word. It runs perfectly on WINE under Ubuntu. The service releases installed fine. It runs with full access to the host filesystem, cut-and-paste, file associations, the lot. And run on hardware a decade newer than it was written for, it is blisteringly fast.

For a project last year, I had to temporarily move to a newer version -- Word 2003. That needed Crossover Office to install properly, but it too works perfectly and supports widescreens and 1080P monitors in portrait resolution just fine.

"[product x] 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 [desired outcome]" is about the most ringing endorsement possible for a product that has to be used by as broad an audience as something like Word.

As a Markdown-loving attorney: Yep. And not just word processors, but Word specifically has non-negotiable features I need, such as tables of authorities.

Yep, you can do any of this in LaTeX—but it’s just much harder, and generally works best with pre-set templates, not so much when you have to make small stylistic tweaks at the last minute without spending an hour debugging.

Markdown + git should offer great value to attorneys. They can manage versions, etc,etc. They can always export to word if the courts require/mandate a print layout, but everything else you've mentioned exists in some version of markdown (like pandoc).

I do agree that coders think the world is like them - wanting to memorize and master markdown syntax and git commands. But, reality has no tolerance for such chicken shit. If markdown+git can be packaged in an easy to use app, easy enough for a 5 year old, it stands a chance

I can't think of a way to do authority-marking and tables of authorities, auto-updating supra and infra references, different page numbering systems within a single document, etc etc with markdown. Writing a rough draft in a text editor is easy enough but the last bits of formatting and presentation for legal documents are just really, really involved.

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.

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

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?

Asciidoc?

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.

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.

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

Looks like several people recommend this script:

https://github.com/dhabyx/riv.vim

Does Leanpub Markua (http://markua.com/) fit into your requirements?

It totally competes with Word for some documents. Of course there are documents that are possible in Word but not Markdown, and equally there are documents that are better to write in Markdown (e.g. Readmes). But there is a decent amount of overlap for documents that are basically lightly formatted text plus pictures.

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.

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

maybe its harder than it looks

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

Markdown was specifically designed to just be shorthand for HTML tags--most of the missing features don't meet that criterion.

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.

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.

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.

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

My setup:

1) I have cmark installed

2) 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_prev...)

3) I write markdown in Vim and use keybindings to say "now output HTML from this buffer" - 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.

Have you checked out Madoko?

https://www.madoko.net

> Madoko is a fast markdown processor for writing professional articles, books, manuals, webpages and presentations, with a focus on simplicity and plain text readability.

> With Madoko you can write complex documents completely in markdown and get beautiful PDF and HTML output.

It's unfortunate that their front page has broken layout.

"Madoko = LATEX x Markd"

I guess it depends on what you mean by "looked horrible". I've found some of the MD to PDF plug-ins for Atom were acceptable for short documents. For bigger ones, I'd probably want more control over formatting, and would go via pandoc.

What is your gold standard here? I can only assume you're comparing to hand-written LaTeX. But if that is a feasible option for you then you might as well stick with it. Using something simple like markdown is really a compromise for non-TeXnical-typists.

I use asciidoc (via asciidoctor), which is based on Docbook and therefore supports a lot more complex document features. Its PDF export is quite excellent IMO, and doesn't require LaTeX (though it can go through LaTeX).

I'm definitely late to the party, but I've used Markdown, CSS, and Weasyprint to make some attractive PDF files (including my resumé, so I put my money where my mouth is). It lets me style things as I like without much extra work, and since Markdown produces simple, predictable HTML, I can keep a library of styles that I can apply to any document.

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.

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.

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

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

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

We do a lot of large design/spec documents so we really make a lot of use of that.

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.

Org-mode can do all of those things.

Emacs is going to be just as obtuse for your everyday business analyst as LaTeX

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

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.

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

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

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

† 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

†† Contemplating moving to headless Chrome. Also, increasingly using Hugo for online documentation.

This looks really neat! I'd love to experiment with this

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

I would strongly recommend looking at weasyprint (http://weasyprint.org/ ) for HTML to PDF. It gives much better PDF output and offers CSS print support, so you get page control.

asciidoc via asciidoctor (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), tables of contents (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).

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

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.

Last time Markdown was written about on HN, someone mentionned Typora (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.

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.

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.

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 [2]: https://texti.github.io

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

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.

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.

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

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

[1] http://www.gabrielgambetta.com/the-golden-legacy.html

[2] http://www.gabrielgambetta.com/tgl_open_source.html

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

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.

and perhaps doesn't realise that .docx is just zipped XML

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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/

I use it almost every day when copy-pasting from from shared google docs.

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.

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.

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

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.

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

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.

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

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.

Reply on news.ycombinator.com