Implementing Latex in our company

Question

I am employee in mid-sized company (roughly 300 employees) which develops and manufactures some medical-related devices. For our devices, we need to write various manuals (roughly 20 people are working on them, most of them have also other duties), which are typically 100 pages long.

Currently, we are doing this with Word 2010, but (needless to say) this leads to various problems and huge wastes of time, like when we need to add or change something in already existing manuals (which happens very often). This is because our manuals contain large amount of figures, lists (I mean the thing that you obtain with {itemize} in Latex), and page breaks. Furthermore, all manuals contain list of contents and most manuals contain list of figures and list of tables.

Because of that, the company (more specifically, me and my coworker with approval from our superior) is looking for alternative, better approaches for writing and modifying manuals. Since the manuals are configured in the way that I specified in previous paragraph, we think (after some “experimenting”) that LaTeX should be better suited for them. Of course, implementing LaTeX in a typical company would be normally a futile endeavor due to opposition (more specifically, unwillingness to learn) from other employees. However, it should be noted that our employees are better educated than average and I dare to say that at least 5 of the mentioned 20 have already some experience with LaTeX.

Furthermore, there is no timeline in which we have to implement LaTeX (or implement it at all), what is most important is that if we decide for it, we do it with a comprehensive approach. Since I believe that some of you have some experience with this, I want to ask you some questions. Note that you don’t have to answer on all of them and that any help (even if it is not related to questions) will be appreciated.

The questions are following:

1. Do you agree with my opinion that LaTeX would be one of best options for writing and modifying our manuals? If not, what alternatives do you suggest?

2. As ALL manuals are configured in roughly the same way, we think that one template (I mean preamble) could be enough to cover them all. How should be preamble formed, as it will probably contain various packages? What rules should be followed inside the {document} itself? And what should the approach be when we want to modify the preamble?

3. For current “experimenting”, I used TexStudio together with MiKTeX as compiler. But if we want to implement Latex more broadly, more thought needs to be put in which program we should use. Which programs do you suggest? Note the following things:

a) What is probably most important is how to ensure that all users have same versions of various packages, same version of compiler etc.. It is important to avoid the possibility that same document would look differently on different computers. Note that our company has centralized IT department and that we use Windows on our computers.

b) What is less problematic is if the look of a document changes due to update in some packages, but in such case we need to somehow notice this. Furthermore, if something goes awry after updating some package (for example, document does not compile), it would be good to have an option to revert to an old package.

c) Also note that manuals are written in various languages. This is why I used TexStudio for experimenting, as it has built-in language check tool.

4. At some point, we need to prepare and educate other coworkers before LaTeX can be implemented. What suggestions do you have about this? I thought about following things:

a) As implementing LaTeX is not a small thing, we can do it in steps. What I mean with that is since there are different types of manuals (on which different people work), we can first implement it for one type (as some kind of experiment) before implementing it more broadly (also can be done in steps). More specifically, the type of manual for which it should be first implemented is the type on which my mentioned coworker works (+2 other employees).

b) Before implementation, I will of course write a specialized manual for using LaTeX. Furthermore, me and my coworker will prepare a training for other coworkers. Note that employee turnover rate at our company is small.

5. Furthermore, what other suggestions do you have that the possible implementation will go smoothly and with positive attitude from our coworkers?

Answer 1

The question is a bit open ended for the format of this site, but I'll attempt an answer.

---

Firstly you need to decide how you are going to use latex.

• Authoring directly in latex syntax?
• Authoring in a structured form such as XML or markdown and scripting a conversion to latex, just as a back end PDF generation?

There are pros and cons to both (we use XML at work although in recent years we've stopped generating PDF from it and just distribute the html version, the manual is 15000 html pages and would be a couple of hundred thousand A4 pages printed, so it's quite big).

---

Which TeX distribution, maybe personal bias here as I have used texlive (originally tetex originally unix tex distribution) for more than 30 years

• texlive
• miktex
• overleaf (texlive as a hosted service)

texlive has always been cross platform and is by far the most common version on linux and mac, miktex was for many years Windows-only, in recent years it has been ported to Windows and Mac as well, so really just choose whichever you want from these two if on Windows, but I'd choose texlive if looking for cross platform usage.

You could also consider Overleaf, being a hosted service there is no installation barrier and all users will naturally get the same setup. For the free version it would make it a bit inconvenient of you want to script generation of files rather than write directly in latex, but the commercial version (which I don't have) allows integration with a local git repository so you can (I believe) fairly easily sync locally generated files with the overleaf project.

---

If you are introducing people to latex you'll need some tutorial references, browsing this site won't hurt but more structured ones include

• learn LaTeX.org
• Overleaf Learn LaTeX in 30 minutes

I should disclose I'm involved in the setup of the first of those (It is available in several languages). The Overleaf one isn't bad even if you don't use Overleaf in production.

---

Answer 2

A few random thoughts for you.

Version control

Because .tex is an ASCII-format, it can be subjected, just like source code, to Git. With Git you can

• establish workflows
• give away any kind of subversions
• receive, check and integrate updates, say by certain employees
• compare versions/updated files
• define and merge branches, e.g. for trials
• etc.

Look e.g. for "Git" by Preißel and Stachmann. There seems to be at least an older version available in English.

Workflows & Modularization

Start mapping and identifying modules of same or similar processes, to cover all or most of the work to create, modify, maintain, distribute your manuals, or "document-snippets".

Try identifying basic szenarios, i.e. different standard ways to obtain certain kind of manuals or parts from them.

Latex learning curve

It can be steep, if you follow books, which introduce Latex. It can be moderate, if you take the burden to preselect and present, what's needed. To understand it, it's a long way, compared to Word. To just use it (e.g. assisted by procedures), it's fine.

Output format

I agree with @Philo Latex is great to create .pdf . What attracts me is the uniform look&feel which is well known from academic publications, journals etc.

If your main format is HTML, Latex may not be the best choice. There is powerful conversion available and under development, though.

Q1: Is Latex best choice? (for pdf)

Yes. Because it's flexible.

For larger documents with multiple user input Word is out of discussion.

Layout-oriented programs like Framemaker or Scribus (free) think in terms of placing frames, which have anything as content, like you'd do in a newspaper (10 info-sections on 1 page).

Personally I use a combo of Scrivener (writing tool) and Texmaker (editor, which starts the compiles). Scrivener lets you structure any content the way you want. So I have a part where I define Latex-necessities, and use self-defined macros in running text. Once done, assemble everything, copy to Texmaker and compile. // However, Scrivener will not work nicely with Git, as you can't easily compare files which are similar (like an update).

Q2: Template

The way you write. // Use \include statements to load text parts of any kind you need (chapters, tables, graphics ...)

However, I suggest gradually building up demo-files, where you basically study your requirements and try implementation ideas. In the end you should arrive at 1 or a very low number of basic templates. (Whether you derive \documentclass{}-es from it, which is quite some work, or just \include your found style (i.e. assembly of packages and macros), isn't really important.)

Q3: Texstudio etc.

Again, perceiving your project as code programming will make things easier. You can create .tex files with any editor you want: so it's possible that each employee uses his or her individual ASCII-editor, e.g. from the programmers world.

You can compile .tex files via a GUI like TexStudio, which implemented the next sentence. Or you can run it from the command line (Windows) or terminal (Linuxes etc.), and via scripts if you need them.

What will be more important is a kind of common workflow, i.e. rules everybody has to follow to make things fit nicely. This can and should cover content, Latex-elements to use or to avaoid, passing files back and forth (Git etc.), and so on.

Q3a: Uniformity + Q3b: Backup

It will be best to talk to your IT department. Perhaps a central solution is possible (e.g. via a local Overleaf installation, find at github, see David's comment). Or you can ensure it via procedures/rules, done manually or automatically. However, you don't want to break an employees fragile work from the last few days (here again Git can be a friend to all of you).

Q4: Rollout & education

What may work well is to look for enthusiastic supporters amongst your employees, just one or a few. They'll be valuable during development, rollout and daily work, e.g. just to help on the fly (supporting).

Q5: Smooth transition with positive attitude

Our attitude is negative, when we feel or realize, "I'm not heard. My input is, my needs are not relevant."

So how to change it? A few methods, ordered from less effective to more effective.

A) Listen. Ask. Talk. Understand. Discuss. Face-to-face, in small groups etc. (M. Gorbatchov and others came a long way this way.)

B) Meetings. (Well, the non-boring, the exciting ones, see below.)

C) Facilitated meetings. Those guys, foreign to your department, know how to mute the loudest and make the softest articulate his or her views. Visible e.g. by tools like pin board, clustered cards etc. (But that's just the tool-set, the versed facilitator uses as needed.)

D) A trend is using Barcamps for half to one day. People like this free format, but results and implementation can be underwhelming. (C might be better, then)

E) (Not intended to be an ad) If we wouldn't still be within the pandemic, with long covid lingering at the horizon for all of us unless there's a cure, you should hire me for "Projekt vertero" (= I will have changed). It's a 3-day process (no phones! no mails! etc.), with groups of 3-12, representing ALL (or most) conflicting views on the subject, like employees, management, sales etc., whoever is relevant. // At day #3 this group comes up with an organic concept pre-accepted by almost all of them. And this group can keep pace afterwards. // Find more, in German, at http://www.ms-spo.de/?id=41 and the links given there. (translate.google.com)

Besides this you should spend a thought on Project Management . There are 3 major schools: PMP, GPM IPMA, Prince2. The first two tend to be academic in the sense "here are all the things you could do ... make your choice"), while Prince2 is a sophisticated adaptable procedure, which incorporated lessons-learned form good and bad projects in a hands-on way: Just do it. They all feel like a burden from time to time ... while I'm sure you'll see and like all the benefits from Prince2 quickly. (Just get their handbook and go, no need for certificates, in my view. ISBN 978-0-11-331533-8 )

Answer 3

LaTeX is not a great format if you ever want to generate non print output. For pdf output with figures, tables, etc it is great. I moved a book that I had in Flare and Framemaker (too complicated for InDesign) over to LaTex for that. But if you need ePub, HTML, Word, etc outputs it is poor. For that Flare, Framemaker, or Oxygen XML are much better.