Hacker News Reader

Comment by bediger4000 | Hacker News Reader

This whole argument presupposes that anyone who cares will get a choice in the matter. We all know that most bespoke software is written for corporations. And despite the immense drawbacks of "Word" (too many to mention, but let's start with autocapitalization...), most bespoke software is documented in "Word" despite "Word" not being fit for that use.

To me, this is like watching intense baseball fans argue who was better, Babe Ruth or Joe Dimaggio - neither one of them is going to play again.

View on HN

This!

So here's a story: I work at a large engineering company building custom automated research systems. The system engineers do the the design/development/testing and documentation.

I have been searching for nearly 9 months for a documentation system to replace our current documentation system (500 Word docs in an EDMS). Goal is to increase re-usability and decrease maintenance cost by something more like a wiki/markdown system.

The problem is, even though formatting and maintenance of Word docs is abysmal, they make inserting images and references drop dead simple. Plus, everyone has it installed on their machine.

All the markdown versions don't have good references or image support (plus the best IDE is gitbooks which is... buggy). RsT is too much of a burden to setup. These are engineers writing, not programmers.

I've looked into Confluence, Gitbooks, Dozuki, Inkling, Sphinx, ... nothing is quite so friction-less to "just write the docs" than Word.

It's not even so much the friction-less nature of "Word", it's just that's what testers, PMs, Managers, Directors, Executive Directors, Vice Presidents, Executive Vice Presidents, etc etc all have and understand. Very few people even seem to find "Word's" grotesque shortfalls as engineering documentation to be a problem. Beyond not being able to ever completely turn off auto-capitalization ("boolean" and "Boolean" aren't the same in Java, people!), the lack of a line-by-line diff makes getting feedback on a document painful and impossible to get correct. Nobody in their right mind would accept binary blobs of code as a "new revision" - you couldn't see what changed, for starters. So why do we just accept WITHOUT THOUGHT binary blobs of documentation? Try to make that argument to a PM, and they'll look at you like you're growing a second face on your ass.

I agree -- I originally wanted a markup language to do away with LaTeX for typesseting but then I realized that getting image sizing and placement right on any markup language is even more painful than with LaTeX, so I just never jumped ship.

I still wish I had a publishing toolchain that produced multi-format output (HTML5, docx, ePub, Kindle, and plain text) from the same source file. It can be done with LaTeX sources but the result is sub-optimal.

As I wrote in another comment, this can be done quite easily with Pandoc. It is a really powerful processing tool and with the right set of templates it can do wonders. Have a look at Kieran Healy's work: https://kieranhealy.org/blog/archives/2014/01/23/plain-text/

For some definitions of "easily". For a programmer, yes.

For an enterprise organization with a full gamut of technical ranges from "maintain 40 github repos for fun" to "I still don't trust anything but Word, Excel, Powerpoint and email", pandoc is not the solution (as nice a tool as it is).

I found references in markdown incredibly simple. Using BibTex or CSL styled JSON objects. Then just chose the CSL style your institution prefers and run it through pandoc. Gives me html, latex, pdf, ePub, and even docbook or TEI for those with an XML fetish.

....but image support. Ugh don't get me started. Thankfully we use it right now for simple articles so the figure doesn't need to do much.

Yeah. I've played around with everything mentioned in this thread, and for documentation that needs refs/math/images, you need to use either Lyx or Word. Asciidoctor might get there if it ever gets a good, free development environment.

Very true, indeed. I gave up on latex and simplified markups and I even abandoned my own converter for this very reason. Today, I use Word because that's what people higher up expect to get.

Reply on news.ycombinator.com