Chapter bibliographies with Zotero and Word

A quick post because I just learned how to do this for my own thesis. Not a pretty post because I need to finish my thesis. But in the meantime...

Have a separate file containing each section (i.e. chapter, supplement, appendix, whatever) that needs its own bibliography. You can edit these later if you need to; don't worry. This isn't all of my files, but I wanted to test it out first. Originally I assembled my thesis is one big file, so I had to split it apart into the subdocuments *groan*

Create a master document. It should have your front matter (e.g., title page, tables of contents, figures, tables, etc) plus anything else that doesn't need a bibliography (e.g. preface, acknowledgments). This master document should have all formatting set up, e.g. margins, header and footers. Although I'm sure you can edit it later.

I find it easier to do this stuff when I can see formatting marks, so I click the "paragraph" symbol.

Within the master document, insert multiple section breaks, with several paragraph breaks between them. U.Laval requires 1) that odd and even pages look different, and 2) that new sections start on an odd page. Therefore, I created multiple "odd page" section breaks like so:

With your cursor in between two of the section breaks, change the view to Outline View.

You should now see any text from your front matter, plus a bunch of section breaks. I've blurred the text of my Preface to avoid distraction.

Click Show Document.
Then Insert.

Browse for your next section (general introduction in my case), then Open.

Your subdocument should now be inserted. If you Close Outline View, you should see the text of the subdocument (e.g., General Introduction) within your master document.

What's more, Word somehow knows to update the table of contents, page numbers, etc with appropriate content from the subdocuments. Which is pretty awesome, if you ask me. 

The really awesome part is that if you need to make revisions (haha, "if"), you don't need to find each file individually. You can use the master document to open each sub document. First click "Show Document" in the Outline View. 

Then click the little icon to the left of the "+" sign. This will open up the original sub document file. Any changes you make (and then save) will be updated in the master document. 

That's as far as I've gotten so far, but it seems like it should work for the remainder of my thesis. I'll edit with an update when I've finished, if I have any extra remarks to add.

Update: Well I discovered that it's perfectly fine (maybe even encouraged) to have a single reference section at the end of the thesis. That's even better. Although the subdocument approach looked promising, it was finicky and tricky. I got the impression that it would be easiest to insert chapters with the last one first, and work my way backwards. 

My ProjectTemplate/Markdown/RStudio/knitr Routine

In January of this year, I posted a summary of my EssentialPhD Toolkit. In that post, I discussed the trifecta of RStudio, Markdown, and knitr. I also mentioned Project Template, an R package that helps keep files organized and can automate some analyses. I learned about and started using all of these tools at the same time, so I’m not always clear on how to use them independently... That said, I learned an integrated routine from a colleague and have adopted it for myself. I’ll share that routine with you in this post. I’m sure it can be improved, so please feel free to leave some tips in the comments. Also, ask me if anything is unclear. 

Pre-steps: Install R, RStudio, and packages
I'm assuming you have a basic understanding of R. Install RStudio and then the ProjectTemplate package. I don't recall if you need to install knitr or if it's automatic, but maybe install it too just in case.

Step 1: Create the project
Within RStudio, run the following lines of code. Change "MyProjectName" to whatever you would like your project to be called.

require(ProjectTemplate) create.project("MyProjectName")

This will create a new folder inside "yourdirectory", filled with several sub-folders, like so:

Folder structure created by ProjectTemplate

Step 2: Open the project within RStudio

Within RStudio, click the Project menu, and select "Create Project".
Within the pop-up window, select "Existing Directory".
Using the Browse... button, find the folder you just created using create.project(), above. In this example, it's called "MyProjectName".
Click "Create Project".

Select "Create Project" from the Project menu, then "Existing Directory" from this window

Browse for the folder you just created in Step 1

The project will load, as you can see in the top right-hand and left-hand corners: "MyProjectName" is the currently loaded project.

Using Markdown and knitr with ProjectTemplate

Open a new Markdown file by clicking File > New > R Markdown. I won't talk about the syntax of Markdown. For that, you can click on the "MD" button next to the "Knit HTML" button. Or you can Google for Markdown syntax.

I also won't dwell on the specifics and mechanics of ProjectTemplate - for that, visit the website, which contains much more detail than I will give here. Here I'm simply providing the extra bits of code I add to ensure that my scripts run smoothly without any working directory issues.

ProjectTemplate relies on the folder structure it created to automate some scripts and analyses. I don't take advantage of this as much as I should, but I do benefit from auto-loading packages and auto-loading any basic scripts (i.e. custom functions I wrote for this project). In order for scripts to be run automatically, they must be saved in specific places and the working directories must be specified in specific ways.

I keep my analysis scripts in my "src" folder. Any data-manipulation and pre-processing scripts are in the "munge" folder. My custom scripts are in the "lib" folder. The first chunk of any of my scripts is a Startup script, which specifies which folder the file is saved in (e.g. "src" or "munge") and then sets the directory one level higher - this step is necessary to load the project using ProjectTemplate.

``` {r startup}
require(ProjectTemplate)
if(basename(getwd()) == "src") setwd("..")
load.project()
```

Depending on how your configuration file is set up, the load.project() function will load packages specified in your config file, load any files within the data folder, load any scripts in the lib folder, and run any scripts in the munge folder. I usually keep my munging and data-loading turned off because my files are big and my munging can take hours.  I prefer to have more customized control.

To my understanding, knitr re-sets the working directory to the "src" (or "munge") folder for each chunk, so I try to add a conditional working directory change at the start of each one. This conditional setwd() allows me to run the script within RStudio AND to let knitr knit the script, without confusing working directories. So, for example:

``` {r load_files}
if(basename(getwd()) == "MyProjectName") setwd("src")
load("../cache/oldanalyses.RData")
```

Note: My colleague recently updated me on how to specify working directories. He said that instead of if(basename(getwd()) == "src") setwd(".."), I should use require(knitr); opts_knit$set(root.dir=".."). To be honest, my strategy works for me and I'm comfortable with it so I likely won't be changing... but I wanted to make sure you're aware of it.

That's the basics of how I start up a new project using ProjectTemplate, and how I navigate some of the issues with working directories using Markdown/knitr/RStudio. If you have any questions, leave a comment. I'm not an expert, but I'll try my best to address your question.

Writing group: Commenting styles, part three

So far, I've written two posts reviewing lessons I've learned from my writing group about giving and receiving comments (part one; part two). In part three, I discuss a technique I learned from my MSc supervisor, and a new technique I discovered via Twitter.

5. The "shit sandwich" 

I typically refer to this as the "hamburger approach", but I think this alternative title is more fitting. This approach is used when writing up an overview of your thoughts on a piece of work, in contrast with my previous posts about actual in-line comments on specific items. The premise of the shit sandwich is to start your critique with some general positive comments. Then you dive into the major issues of the paper, followed by some smaller criticisms. You finish off with some final positive thoughts and an encouraging sign off. In other words:

1. Positive
2. Major negative
3. Minor negative
4. Positive + encouraging

It's totally transparent, but it somehow works to soften the blow. (Contrast that approach with a review that starts right in with a long list of criticisms with nary a positive point to be found). My MSc supervisor used this approach for all his grading, and encouraged us to do the same when reviewing other people's work. I'd say that it's a good general strategy and forces us to say something positive, which is always a good thing.

6. Shit sandwich with extra toppings 

MT @lifehacker: Trouble giving useful #criticism? 4 conversation rules that can help: j.mp/16oRLUc#ecrchat ht @pj_weatherill
— Research Whisperer (@researchwhisper) May 29, 2013

This Tweet showed up in my feed just as I was starting to review the writing of the week, and just after my commenting style had been critiqued. Briefly, the four rules are:

1. Re-express your target's position
2. List points of agreement
3. Mention what you've learned
4. Critiques & rebuttals

I promised my Twitter followers that I'd apply these rules in writing group. However, as I started writing my comments, I realized that these four points weren't quite sufficient for my needs, so I combined them with the shit sandwich (#5) as follows:

1. Positive: Start with broad overall positive feedback
2. Summarize the piece of writing: warning: this can be time consuming. However, I've already discovered that I give better feedback if I take the time to write a one-sentence summary of each paragraph as I read it. I provide this "outline" as an addendum to my comments in case it is helpful. If I've already written this outline, producing a summary of the piece is quite easy. 
3. List points of agreement: this was tricky since the piece this week was just the Introduction and Methods sections. However, I identified an argument made during the introduction and found that I was convinced by it, so I mentioned that.
4. Mention what you've learned:  It was easy to identify something I didn't already know, since the writer this week works on quite different research than I do. 
5. Other specific positive comments: e.g. "your methods section was detailed enough that I could replicate your experiment"
6. Larger critiques: Describe any general problems with the paper (e.g., general organizational techniques) and point out possible solutions. 
7. Smaller critiques: Mention any smaller points (although typically I think these concerns are typically addressed in the inline comments)
8. One-sentence-per-paragraph outline: Not necessary, but something I like to do. 
9. Final positive closing thought: preferably with some encouraging message. 

You'll notice a few things. First, this leads to a LONG REVIEW. However, #7 is implicit in the inline comments, and #8 is totally optional. You can decide how much you want to say in the rest of the review. 

Another thing - probably the most important thing to take away from this technique: Of the 7 obligatory components (omitting #7 and #8), the first five are positive. By starting off with so much benevolent helpfulness (or as one group member put it: "ego stroking"), the harsher critiques seem less threatening, and are ultimately more helpful. 

Seb was the guinea pig, since it happened to be his week. I gave him warning that I was trying a new feedback technique and wanted to know how he liked it. He told me he that he did indeed like it. He found the summary was great for identifying whether or not I understood the story/message of his paper. He also said it was surprisingly pleasant to read about something I had learned. (I guess in hindsight, this makes sense  - theoretically, the point of writing papers is to share knowledge, so it must be nice to learn we've succeeded). He also said he'll try to adopt the technique himself.

Overall, I'd say this technique was a success and I'll probably be implementing it in future writing group meetings and other reviews as well. 

Writing group: Commenting styles, part two

Photo by Ryan Poplin

I previously wrote about a few lessons I've learned from my writing group about writing and interpreting comments. Here are two more.

3. An apparently useless comment may have a hidden message. 

It often catches me off guard (and mildly annoys me) to see comments that seem totally "out there". Comments like "this appears to be the core of your paper" when referring to a tangential sentence, or "this sentence is probably not necessary" when referring to a crucial summary sentence. These and other questions/suggestions that demonstrate the person's lack of understanding are frustrating and discouraging. However, while the content of these comments might be useless at first glance, the comments become helpful if you read between the lines. These "useless" questions and suggestions indicate that some aspect of your writing (whether a specific sentence, paragraph, or the whole paper) led to a misinterpretation on the reader's part. Now the onus is on you the writer to identify the cause of the confusion and remedy it. This process is of course facilitated if you can have an on-going discussion with your commenter (see #4).

4. Commenting should be a discussion. 

My writing group tends to use Google Drive for editing (although Dropbox is sometimes necessary for more polished and formatted pieces). Google Drives facilitates active discussions rather than one-time static revisions and comments that are common with printed paper or Word's track changes. The writer receives email notifications when people comment his/her work, and the commenter receives email notifications when other people (commenters and writer) reply to those comments. This conversation style of editing (while distracting for those who keep their inbox open all day) allows writers to ask for clarification if a comment is too vague. It also permits the easy agreement or disagreement among commenters, which can help the writer decide if a comment is one person's opinion or a general consensus.

Writing group: Commenting styles, part one

Photo by Rona Keller

I got my writing group up and running in March, and it's been very successful so far. As I mentioned in my first description of the group, I've obtained much more than just comments on manuscript drafts. I've learned about the writing process, revision strategies, and tricks & tips that different people use. I've also learned about individual styles to writing, editing, and interpreting comments. And of course, there have been (minor) conflicts that arise from these individual differences.


My style of commenting was recently criticized by one of the group members for being too vague. My initial reaction was that it was simply a "different commenting style" reflecting our own preferences. However, his comments and a few examples he pointed out got me thinking about commenting styles. Below and in my follow-up posts (part two), I've summarized a few of the lessons I've learned throughout my MSc and PhD pertaining to writing, commenting, and revising.

1. Each person has his/her own commenting style. 

In general, people tend to provide the types of comments that they prefer to receive. If someone likes to receive full sentence corrections as demonstration of how a given sentence could be improved, s/he will tend to provide full sentence corrections when editing. Some go one step further to explain the rationale behind their full sentence suggestions. Some individuals prefer to "think out loud" while they comment, or simply write one- or two-word comments as they speed through the manuscript. Some tend to provide comments in question format, many of which are rhetorical, while others expect an answer. Differences in commenting styles can be frustrating, so it behooves the writing group to understand and appreciate each individual's style. Explicitly stating the types of comments one expects when distributing a text can also help.

2. The "teach a man to fish" approach walks a thin line between helpful and annoying. 

Some people (including many supervisors) write somewhat generic or vague comments which put the onus on the writer to identify and ultimately solve the problem. In theory, this commenting style helps the writer improve his/her writing abilities, it allows the writer to maintain his/her own voice or writing style, and it saves the editor's time. However, overly vague comments may not provide enough information for the writer to identify the problem in his/her writing. Commenters in favour of this approach should strive to provide enough detail that he writer can identify the problem, even if a full-sentence correction is not provided.