[Tex/LaTex] Teaching LaTeX and friends

best practicesteaching

Similar questions on how to teach LaTeX have been posted here already, but I would like to give them a slightly different touch:

Has anybody experience with teaching LaTeX in relation with other tools needed for larger projects?

What I have in mind is something like a student seminar (say some 10 dates, 90min each or so) which covers a good introduction how students can write a larger project (like a PhD thesis) using LaTeX, but also in a professional way. I made the experience that student somehow manage to master LaTeX but produce unreadable code (for me as an advisor) and "organize" their work in a rather erratic way (to say it politely).

So I would like to introduce them not only to LaTeX, but also to some "best-practice" concepts in LaTeX. This should include some ideas of how to produce readable code (that the collaborators or supervisors can get into it quickly), naming macros, label, etc. in a reasonable way and so on.

Furthermore, I would like to introduce them to some tools for organizing their typing, like a version control system (personally I use git), a professional bibliography mangement like BibTeX, a reliable editor (don't want to start a flamewar here :), a good production workflow, and exchanging code with the supervisor (maybe even remotely located via git, email…)

To make my question more precise: has anyone suggestions which "best-practice" topics one should cover, how actually they look like, which tools beside the LaTeX core are useful, necessary, superflous…?

EDIT: Concerning the pre-knowledge of the students. This is of course rather unclear to me as well. But to have some idea, let's just say that they have some basic experience with LaTeX, some basic ideas about Linux/bash etc and some basic ideas about the problematics of collaboration. With other words, I do not want to start from scratch but upgrade their skills to a better level.

Best Answer

This is written form my perspective and experience so you might feel this is subjective ... well it is. And of course i always address nature scientists.

First of all i want to say that here are many "best practice" Questions on tex.se, much to many to cite them all. Just go and search for "best practice".

For me with my little latex teaching experience it has turned out, that usual students who come with basic computer knowledge and hopefully with a little knowledge in programming or writing markup (html) do not have so many problems with "thinking" code, while all the others have. A basic latex course usually does not include the following topics and therfore they might be interesting as further topics:

Technical side:

  • unit handling (siunitx) structuring and markup
  • glossary handling (glossaries)
  • plots (pgfplots) and pictures (tikz)

Non technical side

  • typography
  • common rules for academic writing (such as DIN ans ISO)
  • dismissing obscure guidelines (given by non typographers) in a self confident way

Non LaTeX side:

  • how to choose the best editor
    • texworks
    • kile
    • texshop
    • txc
    • texmaker (or one of the clones)
  • enhanced bibliography managment
    • bibdesk (mac)
    • jabref
    • refworks
  • rcs
    • hg
    • git ....

I want to go a bit more in detail:

The editor

Well choosing the right editor is rather complex. What i saw while teaching complete beginners was that they easily become overstrained when using a more complex editor such as kile or texmaker. Secondary i believe that using the same editor for programming and for latex (eclipse e.g.) is not a good idea. The editor should provide code autocomplete (TAB + X), support synctex (you should tell your students how to use that) and minimal project management (e.g. by setting the main document).

Bib management

I really can´t understand people who do not use a automatic bibliography management system. But as TeXnican one should not even think of not using bibtex or biblatex. How to create a output of a bibtex-database should be part of a beginners course, creating the database itself with 3rd-party applications or by hand might be part of another course. I would say they needed to be introduced into a standalone tool such as jabref or bibdesk (mac). Depending on the environment your institution (university i guess) provides it could be useful to show them how to export e.g. from refworks to bibtex database.

Collaborative working

Well i think that LaTeX is somehow perfect for a distributed and collaborative work. I personally use hg , because it seems to be more handy than git. I also used the todonotes packages a lot to mark my document. But that might not be suitable for every situation. For email distribution it turned out to be useful to split the document into very very many small pieces so that almost everyone works with one or two separate document pieces only. This procedure requires a distinguished maintainer who puts all the pieces back into one.

Asking for help

Even old and wise people sometimes have problems with asking in the right way. So it definitely needs to be said, that even TeXperts do not have galadriels mirror, and guessing where a certain command comes form is very fatiguing. Not that this topic needs to be extended to the limit, ten minutes some when in the course should be enough to induce a awareness on this topic.

And of course the best of all "best practices" in the field of getting help is to use texdoc. Please please tell them about its magic!

--- to be continued ---