Teaching LaTeX and friends

Question

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.

Answer 1

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

Answer 2

I can give you some partial feedback on the "enforcing good practice" aspect of what I did when I taught LaTeX to undergraduate math students in order to learn them how to do a memoir (it was a bit early for them to write a PhD). You should be able to adapt some of it to your situation, although it really only concerns the coding aspect. It was a few years ago, but you can see the teaching page on my website.

Choice of editor: I imposed a simple editor (TeXmaker) which works on all platform. The advantage is that everybody had the same editor and so I could described things only once and in case of any problem, the solution was the same for everybody. Of course, if you have computer science students or non beginners with LaTeX, imposing an editor might not be ideal.

Enforcing good practices: as they were nearly all beginners, I did not have to fight bad habits, and instead enforced a strict policy on how they should use commands, where they should put them in their preamble (a "standard" preamble was given to them for the need of the course) and what commands they should use in the document (e.g., no \\ other than inside a table or an align, no \bf, \it or \sc, no {eqnarray}, etc.) and what the sanctions in terms of grade would be. The result was quite good, as only a few of them made these kind of mistakes. The students had access to the two documents (both document are in French, unfortunately) list of errors you should not make with LaTeX and Advice to write a LaTeX document wel. At the end of the course, I also did a class on their most frequent mistakes and how to correct them (see seance_12_cor.pdf).

Organisation of the classes: each student was behind a computer and given a sheet describing the topics (e.g. how to type math), each description being followed by one or more exercises. The advantage was that each student could go at his own pace. Each class was 2 hours long once per week over a period of 12 weeks. The first 5 were on the basics (title, sections, table of contents, maths, bibliographies (without bibtex), tables, images, TikZ) and then I went over to more advanced topics (changing the presentation with titlesec, titletoc, etc., using bibtex, making an index, a glossary, how to organize long document using \includeonly, doing more advanced graphics with TikZ, making animations with animate, etc.). Something I felt important was to introduce the concept of macro in the first class and discuss when it is a good idea to define a macro for something; later on, we talked about macro factorization (e.g. \newcommand{\numberset}{\mathbb} and then \newcommand{\R}{\numberset{R}}).

Grading: the students had to give me three homework projects. The first two were reproducing the code source of a given PDF (see files DM1.pdf and DM2.pdf), the second one being the same document but with a different preamble to see if they had assimilated how to use packages to change the presentation without modifying their document. The third was to make a document of their choice of 6-10 pages using certain mandatory elements (equations, table of contents, bibliography, etc.). To encourage the enforcing of good practices, the grading scheme I used was: they started with a grade of 15/20 or so and for each error they lost points (depending on the mistake). To compensate, I also put bonus points for good practice enforcing (e.g. very well presented code) or for complex figures/animations which had taken them a great deal of time to do.

Answer 3

Check out the syllabus I put two years ago: