5

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.

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

  1. Furthermore, what other suggestions do you have that the possible implementation will go smoothly and with positive attitude from our coworkers?
5
  • Really it's good thought to keep the manual in LaTeX, I'm ready to assist you if any help needs...
    – MadyYuvi
    Oct 26 at 13:32
  • I miss not using Latex at work, having used it for technical documentation in the 90s and the mid 00s. The ease with which it can be used with software versioning systems like svn or git is valuable. But I imagine it will be a tough sell. Adobe Framemaker is popular in this space.
    – dedded
    Oct 26 at 13:37
  • A key question you need to answer is if you want each of the employees proficient in using the prepared stencil, or if you wish to have a few key employees who use the LaTeX and develop a text-based interface for the rest of the employees to feed information to the "LaTeX group" for document preparation. In the former case, you need one or more LaTeX gurus as the "go-to" people, when less proficient employees hit stumbling blocks. Oct 26 at 14:17
  • Currently, I think that first option would be better.
    – t387
    Oct 26 at 15:02
  • @t387 In my former organization (US Army Research Laboratory, ~2000 total), I developed the technical report document class and stencil for those who preferred LaTeX to Word (~100 researchers). While not my primary duty (I was a research mechanical engineer), I made myself available to assist any would-be user in getting over stumbling blocks or pointing them to solutions to their questions (often using this site). In our organization's case, it was definitely key to have me available to help people. Oct 26 at 16:20
4

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

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.


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.