preparing manuscripts

I recently discussed the preparation of manuscripts. My focus was on how you can increase the efficiency and accuracy of the process of collective writing. My thoughts are derived from, and geared towards, the kinds of writing that we do in LCV. I include some thoughts on using LaTeX and BibTeX, for example, which are widely used here, but may be relatively uncommon, or unheard-of, elsewhere. Having said that, most of my ideas, such as to use tools to allow all authors to simultaneously edit whenever possible, should apply to other kinds of writing and other collaborative processes.

I wanted to visualize what the steps in writing a manuscript are, what the tools are used for doing each step and how the overall process could be improved. I also wanted to capture who does what. I made a popplet (see below). I include guesses at who normally does different things (left side with magenta popples and second from left column with red popples). Consider that a set of tools (blue popples) for these alone would probably be something like Google Docs, Skype, Preview, JabRef, TeXstudio (what used to be TexMakerX), MATLAB, Adobe Illustrator, Apple Numbers (iWork), Gmail, Time Machine. Thoughts about what you should do as orange popples and some other notes to self as green popples. I’ve also made a table (**+here is a PDF) that lists different tools that you might find useful, some of which you may not know about.

For authors, I considered two groups, those who focus on adding content and commenting on existing content, and those who in addition to writing, complete smaller tasks, which have less to do with content, such as editing the references, or recompiling the paper from its source. I think of the latter as being one person, although it can be more than one. Sometimes two out of several authors would do those kinds of things, but normally everyone wouldn’t. I call these groups ‘everyone’ and ‘one person’.

So what are all the steps? They include: writing text; discussing everything; commenting on stuff; adding references; compiling the source (assuming there is one); exporting plots; making and editing figures; keeping track of stuff (e.g., different runs of an optimization); backing up everything; and sharing among ourselves and with others.

1. Use Google Docs (or some other cloud-based tool) for writing text. You could also consider Verbosus (good for TeX), Adobe Buzzword (which looks cool), and Pages (with iWork.com). This is the right idea because it allows everyone to work on it at the same time, and it eliminates all steps involving keeping stuff in sync (emailing back and forth), which in itself eliminates a lot of headache about things like naming conventions. I believe that these cloud-based tools are essential regardless of how many people are working on it. Even with only two, not having to email back and forth saves a lot of time. The point about editing simultaneously is not really refuted by saying you only really need to do that when you’re facing a deadline. Actually having a single document that everyone can edit in real time means not even having to worry about it. You can just add text.
2. Agree before working on the paper (or whatever) to only leave comments in one place. You could say, for example, that you’ll only comment on the text with ‘Insert>Comment’ in Google Docs. That’d be a cool choice because everyone can see it, it’ll stay there, it can be updated or resolved, you can get email reminders when stuff changes. The point is that if someone comments outside of that, such as by emailing a list of changes or thoughts, you’d remind each other that you want to keep everything on Google. The thing about not having a standard for that is stuff ends up all over, increasing the load on a subset of authors to put stuff in sync. It also means that everyone has to check many different sources to see the comments. Imagine you come back to the text a couple years later and you recall someone saying something about some chunk. But where did they say it? You may have to look in your email, you may have to look on things you’ve scribbled in your office, you  may have to look in previous downloads of the source (where it might be as a /comment). More than likely you’ll never be able to track them down. That might imply a good commenting system would be one where you can resolve stuff, but where the comments are not deleted. Something to consider.
3. Use a full-blown reference management tool like Mendeley or Zotero with a shared (cloud-based) folder for the paper rather than something like JabRef. The advantages to doing so are similar to those for Google Docs, including that everyone can edit in real time. Other options include colwiz, which should be similar. Another option is EndNote, which seems like it doesn’t cover the same functionality (e.g., reading and annotating). It’s not clear how to make it all work with the Google Docs to LaTeX thing. Integration with Google Docs, might be helpful, but even that alone might not work with TeX documents? You could try exporting to BibTeX and having that export be in a shared (cloud-based) project folder, such as one in Dropbox.
4. Use TeXworks (or something like it) for TeX front end, for doing compiles). It’s probably more tool than you’ll need, but at least it’s stable and likely to work. Other options include TeXstudio and TeXShop. Remember to never edit in the .tex itself. Sometimes that’s necessary, like when it won’t compile and you need to fix something. Normal thing then would be to make the change and copy and paste back into Google. Seems like bad form. Keep the PDF in the shared folder for the paper.
5. Give everyone access to the MATLAB code, so everyone has same scripts and outputs.
6. Consider saving all figures as EPS so people can use any vector graphics editor on them. It’s not clear whether that’s perfect, though, so you’d want to check it. It’s possible that there would be differences with editing in various editors and things that don’t get saved out. If everyone is cool with using Adobe Illustrator I’d go with that. Again agree that you’re not going to edit stuff with different tools or with tools of different versions.
7. Don’t share things via email. Use Dropbox on the main folder and put everything that’s not on Google Docs (or some other cloud) into the Dropbox. If you want to send something to someone outside use YouSendIt. You could also give them a link to the Google doc or put them on sharing there. It might be necessary for everyone involved to have a Dropbox account (and something like 50 gig), which is unlikely. If that applies, would need to figure out some other way to do this.
8. Have a plan for backup. One can assume that the stuff on Google Docs is backed up their side, but you will also have copies of stuff from the downloads. Can probably make a Time Machine backup on the main project folder, although not clear how that works with Dropbox folders.

adding publications to your cv

Umesh recently discussed how to automate the ‘Publications’ section of LaTeX-based CVs (associated files, example CV). His desiderata for Publications: reverse chronological order; organization by type (e.g., for journals, conferences, abstracts and talks); and his name in bold. He doesn’t want to enter this stuff manually and he’d like it to match what shows up on his website.

For those who know Umesh, I’m not sure it really needs to be explained, but why LaTeX for this and not some other WYSIWYG option like Microsoft Word. Well, for one thing it’s WYSIWYG, which means it can be challenging to keep the formatting consistent. I want to say that using styles in most WYSIWYG makes consistent formatting relatively easy, although maybe not as straightforward as in LaTeX. Anyway, separation of content and style is a good idea and it’s something LaTeX is good at. And, though he didn’t mention it, there are lots of free tools for writing with it, absolving you of a lifetime of Office purchases.

One thing you might consider, though, is that some places require that you submit these kinds of documents as a .doc. Once upon a time, we worked really hard to convert a .tex, either directly or through the .pdf, into a .doc. Our conclusion then: if it can be done it’s highly non-trivial.

So BibTeX (what we use for references in LaTeX). It’s good for citing in papers, but getting it to do what we want (see list above) is tricky. Not to worry, it can be done with the datatool package. What follows is the version-by-version. Check the associated files for this post to see how this is done. You should be able to modify those files to make this stuff happen.

Version 1 looks ok, meaning it works, but the first thing is it’s not in reverse chronological (2008, 2009, 2003..).

Version 2 has the sorting worked out, starts with 2010, but isn’t grouped by type. It’s just a big list.

Version 3 gets grouping, and is only lacking (with respect to our list) in that names aren’t highlighted.

Version 4 has the name highlighting.

In summary, use BibTex and Datatool. Also, Rob’s bib2php (which I wrote about here) can use the same BibTex to add your references to your webpage. Other uses of Datatool include creating a list of papers since a particular year, creating a list of 10 most recent publications and managing multiple bibliographies. Problems include that output styles are limited and it may be slow to compile for many references.

adding publications to your website

Rob recently discussed how to add your publications to your website using his bib2php, which, as the name implies, converts BibTeX to PHP. bib2php was developed at LCV for this purpose, to add all of the lab’s publications to the lab’s website. Here is what the output looks like. I’ll describe some of this more below, but note that the main output shows lists of publications, with the standard stuff like title, authors, etc., and links to the ‘Abstract’ and a ‘PDF’ when it’s available. It gives you different options for sorting publications (e.g., ‘Year’ ‘Type’ or ‘First Author’) and allows you to exclude certain types, such as for ‘Conference Abstracts’.

Why should you care about this? It can save you time and effort. You won’t have to update them separately, meaning you can just update your BibTeX and everything will work with the webpage. It’s ‘feature-rich’ and ‘customizable’.

As I mentioned, the basic features work with just your BibTeX. Sort stuff by BibTex types, date and author. Exclude BibTeX types. Get an abstract page (which shows the abstract) with author links and publication links, which connect something to related documents.

To get the most basic features working, you need to edit bib2php.conf. It’s a configuration file with three things that you need to change: the name of your .bib file, where it lives on your server and a setting to turn off display of the LCV header.

To get the advanced stuff working, you need to edit bibaux. It’s where you would handle supplemental stuff, downloads, related documents, awards, superseded papers, cover pictures and document types not defined by BibTeX (e.g., conference abstract/paper distinction, talks, posters).

Customization includes through CSS and the printSelf function, which allows you to change the printing style for existing document types. You can define the style for new document types.

Future versions should include topics, which will be tag-based, and allows you to sort and exclude by topics. You will also be able to create automated topic pages. Also, a GUI bibaux editor and a more generic BibTeX parser.

To get a copy, email Rob, and if you don’t have his email email me. And if you don’t have my email use ‘Ask me anything’.