6 ms·
My problem with LaTeX is that a ton of programmers think it's a good idea to use LaTeX instead of, say, Word or Writer or plain text wrapped at 80 characters or
by da_chicken 9y ago
My problem with LaTeX is that a ton of programmers think it's a good idea to use LaTeX instead of, say, Word or Writer or plain text wrapped at 80 characters or a Wiki for things like process or project documentation.
Programmers love to use LaTeX, because they get to feel like they're doing something exciting like writing a computer program when what they're actually doing something incredibly boring like writing documentation. They get to use the same plain text editor they're familiar with. They get to use the same version control that they use with their code. I've seen programmers try to use many justifications for why LaTeX is important for their doc because LaTeX has some feature that everybody knows they don't actually need to use.
The truth is that unless you have a literal need for actual true typesetting, you should absolutely not use LaTeX for documentation. The reason for this is two fold:
1. "First, you need a properly configured LaTeX build environment," are never, ever the first words that anybody wants to hear when they need to read, update, modify, and manage documentation. Documents that are not going to be published outside the company should never require a build environment.
2. No matter what your job is, you're not going to have it forever and someone will probably be in it after you. If all your documentation is written in LaTeX, then suddenly, "Ability to write, modify, and maintain LaTeX documents," is a mandatory requirement. That's a significantly higher bar than "Ability to write, modify, and maintain Microsoft Word documents." Congratulations, you just added significant complexity to your job for essentially no benefit to the company.
The only time you should favor LaTeX is when you're writing a document that will be published and is essentially entirely text. You're a mathematician or some other discipline and actually need to write extremely complex symbology. You have extremely complex and numerous references to manage. You're writing a high level research paper. Congratulations! You're the intended audience for LaTeX.
If you're a software engineer writing standard documentation, put the text editor down and use Microsoft Word. Documentation is meant to be read by everyone, not make you feel good about being forced to write it.
- seanmcdirmid 9y agoNot many go into LaTeX "loving it". Many of us try Word first, and are just unhappy with its output. If you need something that is well typeset and don't want to spend a few $10k on professional typesetting software, LaTeX fits the bill well. Everything else about LaTeX is a pain, not a joy. Is a lot of documentation written in LaTeX? I would never use it for that. Paper that is going to be submitted to a conference? Sure! Blogpost? No, documentation that is read only online...also probably not. But I don't think I would use Word for that either, Word is a pain if you need something other than very standard formatting.
- jacobolus 9y agoThe current version of Adobe InDesign costs $20/month on subscription. Used copies of older versions can be found for relatively cheap. I would advise anyone who values their time against using LaTeX for any document that doesn’t primarily consist of mathematical formulas.
- nobleach 9y agoI used to do all my docs in Adobe Framemaker. The output was amazing. The software itself felt a little obtuse, but seeing the printed pages was great.
- seanmcdirmid 9y agoFair enough. My wife uses Adobe tools for typesetting, she is a professional (she pays $100/month for her CS subscription, however). I'm not a professional, I've looked at the amount of effort needed to refine output in these tools and they make LaTeX look usable...
- jacobolus 9y agoI find that in most cases InDesign takes an order of magnitude less time/effort and dramatically less frustration to get a particular careful output than MS Word, LaTeX, or other commonly available tools. Your wife probably has difficult requirements and exacting quality standards, and could likely get output with quality equivalent to common documents prepared using amateur/automatic tools in a much shorter time, if she wanted to. It’s almost impossible to do professional quality typesetting in MS Word. Last time I really tried was about 10 years ago. I spent like 4 hours trying and failing to fix basic typographic mistakes in another person’s 20-page document, and then gave up and did the whole thing over in InDesign in 20 minutes, with great results. In LaTeX, you can theoretically do anything you want but unless there’s already a template for it (or you have numerous or long documents targeting the same output style, for which you want to make a template and then mostly rely on automatic layout), it’s going to take a huge amount of time. It’s a good tool if you want output that is “good enough” for many practical purposes without direct human input, but it is especially difficult to do anything special-cased for a particular spread (moving images, text boxes, diagrams, ... exactly where you want them). LaTeX is great for things like auto-generated documentation, long structured outlines, legal documents, or math papers full of complicated formulas. LaTeX is abysmally ineffective for posters, magazines, or the like. I find that for the vast majority of content in between those extremes (e.g. college humanities homework, non-technical journals, resumés, menus, coffee-table books, novels, poetry, personal letters, ...), InDesign ends up giving nicer output with less headaches.
- hueving 9y ago>Documentation is meant to be read by everyone, not make you feel good about being forced to write it. I think you missed the point you were trying to make here because nobody has any difficulty reading the PDFs rendered from latex.
- da_chicken 9y agoYes, but maintaining documentation in PDF is not. Half the people that manage our doc are non-programmers. They're not learning LaTeX. They're not editing raw PDFs while the other half of the team uses LaTeX.
- hueving 9y agoThen you should have focused on maintainability in your comment, not legibility.
- spc476 9y agoI was with you until the last paragraph. Microsoft Word? Really? I can still read plain text documents written in the late 70s. Can't quite say the same for VIP-Writer. Or even Word Perfect.
- SAI_Peregrinus 9y agoBoth your issues are solved by LyX. It removes most of the pain, and what remains tends to be with adding obscure document classes anyway, which you don't need for documentation.
- geofft 9y agoSince this is a forum that values reasoned debate, it would help if you actually argued against "They get to use the same plain text editor they're familiar with. They get to use the same version control that they use with their code." instead of just dismissing them out of hand. Those seem like important things! Also, what's wrong with apt-get install texlive-latex-recommended (or better yet having your IT department / your provisioning system for new developer machines / whatever do that for you)? If your position was "Documentation edited by lots of people should not require weird CTAN modules," that I would agree with. You can write perfectly good documents of all kinds with just what's in texlive-latex-recommended.
- mixmastamyk 9y agoWas with you until your recommendation for Word for documentation. Something like a wiki or Sphinx would be much more appropriate than a flawed and proprietary one.
- xigency 9y agoThe proper tool is whatever the IT department has installed on everyone's computer by default, and failing that, something simple and easily edited (like raw text or markdown). I think the proper analogy is like editing documentation in PDF. Software that can edit PDFs is expensive and difficult to use, like LaTeX can be (difficult, not expensive, just in terms of time).
- mixmastamyk 9y agoYes, though neither a wiki or text editor need to be installed, therefore even more accessible.
- greenleafjacob 9y agoDo you think legal writing falls into this category?
- mark212 9y agoI have a dream where someone writes a processor that will allow the writer to bang out some Markdown-ish plaintext and turn it into a p&a with automatically generated Table of Contents, Table of Authorities, caption, and pleading paper. Call it LexDown or something even less mellifluous and free millions from the tyranny of Word style sheets forever.
- da_chicken 9y agoAs far as I'm aware, the vast majority of legal documents are still written with Word or Google Docs. Nearly everybody went to Word when WordPerfect died.
- hyperbovine 9y agoWow, this is just so far off the mark I don't even know where to begin. LaTeX excels in three areas that are crucial for writing complex documents -- cross references, citations, and indexing. You clearly have not had to endure the house of horrors that is the MS Word ToC, or trying to get autonumbering working as you wish for sections, figures, and tables, or managing a large (100s of pages) multipart document, or any one of a bazillion other little asspains that crop up when forced to use Word for a nontrivial task like maintaining documentation for a large complex project. And point #1 is a complete straw man, setting up a TeX env takes 20 minutes and the basic doc format has not changed since the 1990s at least.
- theparanoid 9y agoI thought Latex was superior to Word in every way than I had a colleague that knew Word. Word if you learn it is just fine generating a ToC or autonumbering sections, figures, and tables. In practice, Markdown is better than either for documentation that isn't printed. It's easier to edit, can be viewed with a plain text editor, and has a minimal learning curve.
- catamorphismic 9y ago> I thought Latex was superior to Word in every way than I had a colleague that knew Word. Word if you learn it is just fine generating a ToC or autonumbering sections, figures, and tables. No, it doesn't work well even if you know what you're doing. It's much better than when blindly trying to hack your way through, but there are still so many weird quirks it does which you always have to spend a lot of time on.
- Too 9y agoI would say it works well if you know what you are doing, but in a shared document there is always some dumb ass in the team that does some manual formatting like using the bold-button instead of changing header type, or remove a link from an image. Then the all the references and indexes are beyond repair with the only way to salvage the document is to slowly, meticulously and painfully go through it in this outline-view and try to identify what should be a header and what should not. If only there was a way to create a Word document that forbids manual formatting it could actually be usable.
- no_wizard 9y agoOr markdown or restructured text or ascii doc. I mean it’s not like it must be either LaTex or a word processor. Markdown is sufficiently easy to turn into text nowadays there’s really no reason not to first instance. And that’s assuming someone agrees with the general premise of this argument which I don’t think I do
- isatty 9y agoI'm sorry I disagree. Word is absolutely horrible for programmers to write in. It makes even the simplest of formatting repetitive and boring. It does not do automatic layout (things I DO NOT want to bother myself with) nor syntax highlighting. Just use Markdown if you're so concerned with people writing Latex.
- jnxuw 9y agoIn addition to the other comments, being able to use version control on software documentation is a critical ability. If you develop software without a distributed version control system, you are just stuck in 17th century and there is no need to discuss further. If you use version control for your code and do not treat documentation as an integral part of the software which accompanies each version, this makes the impression that documentation is just an afterthought. To address the 'environment' issue, it is, in most cases, unproductive to not work on Linux where all of this stuff works out of the box. Also, your idea that it is easier to write a /good/ document using Microsoft Word than using LaTeX hugely underestimates the complexity of MS word for anything moderately complex, and even more hugely overestimates the complexity of using LaTeX for simple things. Somebody who has the job to write code in Python or Go should be easily able to document an API in LaTeX within two hours. And to add finally, maybe you don't believe the world will continue to move without using MS office. Be assured, there are quite a few large companies which have ditched office (say, Google) and this was not the slightest obstacle to their further success.