Collaborating with the non-TeX-savvy

Question

What tips do you have for collaborating on a LaTeX document with people who may not be as TeX savvy as you?

For one example and potential problem case: Consider you have a set of new commands and style files you use and normally keep in your own personal style file:

\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{jhwmath}
\RequirePackage{amsmath}
\RequirePackage{mathtools}
\newcommand{\bvec}{\mathbf}
\DeclarePairedDelimiter\inp{(}{)}
\newcommand{\rdf}[3][\!]{\frac{\rd^{#1} #2}{\rd #3^{#1}}}
% ... etc.

What do you do with them? Do you include the style file? Do you put it in the preamble of your file? Do you forgo the \newcommand's for just writing out the TeX? Why?

I'm looking for a way to effectively and efficiency collaborate with non-TeX-savvy while sacrificing the least amount of my own LaTeX customizations and style file choices. What is reasonable to expect from TeX collaborators and what is not?

Answer 1

First, make sure that you and your coauthors use the same TeX distribution. Suppose your co-authors use some form of Windows: if your main computer is a *nix machine and you use TeXLive, then try hard to get your coauthors to use TeXLive for Windows.

Second, make sure that everyone is using the same vintages of all latex packages.

Third, make sure your co-authors use a text editor that's reasonably TeX-aware. Put differently, if they use Windows, do try very hard to discourage them from using notepad.

Fourth, and this is not so much a matter of somebody being more (you) or less (your coauthors) TeX-savvy, but a matter of sound resource management: use some kind of version control software and find a way that everyone has equal and instantaneous access to all files, be this via a shared dropbox folder, a github account, or whatnot.

Fifth, especially if your coauthors are new to LaTeX, do yourself a favor by cleaning up your LaTeX code thoroughly before you let them see it: consider removing all deadwood code, not loading unneeded packages, providing lots of comments and whitespace in the LaTeX code (never a bad habit anyway, right?!), and providing some reasonably self-explanatory templates for items such as tables and figures.

Next, if you've written some specialized macros, make it reasonably easy for the co-authors to access them, e.g., with a keywords interface, and provide some kind of input sanity checking so that the improper setting of a parameter doesn't cause crashes followed by much gnashing of teeth. Don't expect things to go well with your co-authors if your macros take more than three inputs. If your macros are buggy and require sifting through TeX's cryptic error messages, don't inflict them on your coauthors unless you want to terminate some relationships for good.

Last but not least, give them (i) a list of URLs to the online user guides of all important LaTeX packages you're going to be using and (ii) both a hardcopy of and a link to Tobi Oetiker's Not So Short Introduction to LaTeX2e. And, be sure to point them to these documents repeatedly, whenever they get confused, irritated, or both.

Happy TeXing!

Answer 2

You could use a central, shared location where you can store an up-to-date version of your package jhwmath. Either on Github, Pastebin or perhaps even DropBox. Make sure that it is a fixed link, and request they use an updated version whenever they compile a new document.

The latter (DropBox) has the advantage that updated files can be synchronized on various computers with just a internet connection; that is, whenever an updated version is available, it is downloaded. At the moment, a shared folder provides read & write access to users. However, future updates to DropBox will include setting permissions so that "non-TeX-savvy" users will not overwrite your "TeX-savvy code".

Answer 3

As far as I can deduce from the code you provided, this collaboration is probably for a maths discipline. You need to include the full preamble in the TeX file. It is reasonable in such a field to expect that they have adequate (La)TeX skills. Otherwise you in for a tough time and the only possible way to collaborate is via marking comments on the pdf. If you go this route I would recommend you use crocodoc.

\def\pfbox % new experimental version (DEK, November 88)
{{\ooalign{\hfil\lower.06ex % a smiley face
 \hbox{$\scriptscriptstyle\frown$}\hfil\crcr
 \hfil\lower.7ex\hbox{\"{}}\hfil\crcr
 \mathhexbox20D}}}
\pfbox
\bye