Automating Sprint Review Slides with Pandoc

Dickson Tan — Fri, 12 Jun 2020 13:51:45 +0000

In the MyCareersFuture team, we conduct sprint reviews at the end of the sprint to showcase what the team has achieved. We use PowerPoint slides to highlight stories that have been done and those which are still being worked on. Preparing this by hand was time-consuming. Here's how we automated the process.

Getting Story Data
Generating PowerPoint Slides
Customizing Appearance of Generated Slides
Limitations
Conclusion

Getting Story Data

We use Pivotal Tracker for project management. The Pivotal Tracker API returns stories in the current iteration or sprint via the /projects/{project_id}/iterations?scope=current_backlog&limit=1 API call. The response looks like this:

{
  "finish": "2020-05-19T00:00:00Z",
  "kind": "iteration",
  "start": "2020-05-04T00:00:00Z",
  "stories": [
    {
      "kind": "story",
      "id": 563,
      "created_at": "2020-05-19T12:01:00Z",
      "updated_at": "2020-05-19T12:01:00Z",
      "estimate": 3,
      "story_type": "feature",
      "name": "Complete construction of the Expeditionary Battle Planetoid",
      "description": "Palpatine was impressed with the PoC, make this one bigger",
      "current_state": "accepted",
      // lots more data for this story
    },
    // data for other stories in that sprint
  ]
}

Generating PowerPoint Slides

Programmatically generating a PowerPoint file isn't for the faint of heart even in a language that has a library for the task. This is where Pandoc comes to the rescue.

Pandoc is an open source tool that converts between almost any markup format that you can think of, including from markdown to PowerPoint. By using the Pivotal API, I wrote a tool that outputs markdown source which Pandoc then converts into the actual slides. Here's what the markdown might look like:

---
title: "Sprint 63"
date: 18 Sep - 02 Oct
---

## Sprint backlog - Done!

*Jobseeker*

* Create a service/API to serve constants to all other modules (5 points)
* change redux code to Typescript for ui-jobseeker
* Populate the content placeholder on the category landing page with the html content (batch 2)
* Implement page title and meta description for category landing page (batch 2)
* Revise content piece, page title and meta description for Risk Management category landing page 

*Employer*

* Add "Employers Toolkit" link in Employer navbar

## Jobseeker - In Progress Features

*Delivered*

* Implement VDP link for MCF jobseeker and make changes to footer

*Finished*

* Implement GA tracking on the recommended jobs on the application confirmation page
* Switch to MCF figures for application count of all jobs
* Include "Search term" in recommender API
* Implement recommended jobs on JD page (getting the jobs from DSAID API)
* Implement data science tracking for view JD page
* Set up company profile page
* Implement data science tracking for the jobs returned on each page of the search page

*Started*

* Change copy for government scheme section on JD page and search results page
* Implement recommended jobs on JD page (frontend)
* Company profile page - jobs section
* Company profile page - About the company section
* Company profile page meta description
* Take contact number and email address from MCF instead of MySF 

## Jobseeker - In Progress Chores

*Started*

* Improve stability of job application tests
* Jobseeker: Cypress Tests for GA calls

Saving that to a file named presentation.md, the following Pandoc invocation generates presentation.pptx:

pandoc presentation.md -o presentation.pptx --self-contained --reference-doc=template.pptx --slide-level 2

When there is too much content to fit into a slide or if ad hoc changes need to be made, the generated markdown and PowerPoint file can be edited afterwards.

The references to "Jobseeker" and "Employer" are the 2 squads in MCF which implement the jobseeker and employer facing portions of the product respectively.

Here's how markdown's semantics naturally map to slides:

Lines 2 and 3 in the source above specify metadata about the document, title and date in this case. This is part of Pandoc's support for front matter and causes a title slide to be generated with this information.
Pandoc was configured to use a slide level of 2. Hence, the level 2 headings are used as slide titles of new slides.
Text between level 2 headings appear on slides as content. Any markdown formatting there such as lists and emphasis causes the corresponding formatting changes in the output.
A line with 3 consecutive dashes (---) causes a new slide to begin after that point. This isn't used in the example above but is very useful when content needs to be split between slides without creating a title for each slide. Refer to Pandoc's user guide for other directives to insert pauses, incremental lists and speaker notes.

Customizing Appearance of Generated Slides

The --reference-doc=template.pptx argument instructs Pandoc to use a PowerPoint template which provides some control over layout and formatting. Although Pandoc technically supports using your own templates, Pandoc crashed often when I tried doing so¹. Hence, I recommend exporting a copy of Pandoc's default PowerPoint template and using it as a starting point for customization with the following command:

# writes Pandoc's default PowerPoint template to template.pptx
pandoc -o template.pptx --print-default-data-file reference.pptx

Open this file in PowerPoint and under the view ribbon, activate slide master view.

The first slide is the master slide. Changing the formatting of the title and text at various list levels applies the corresponding formatting when used to generate slides, a poor man's CSS.

Here's the Slide Master for our sprint review slides set to use the Arial font instead of the default Calibri. Notice how this matches with the content slides above.

Similarly, here's our Title Slide layout.

Limitations

The format of content was kept as simple as possible - essentially a title and content in lists. Pandoc's PowerPoint writer technically supports a 2-column layout and the use of tables. However, we ran into issues because we could not adequately customize the formatting applied to our needs. For instance, each column in a table could not have different widths causing text to often go offscreen.

Besides PowerPoint, Pandoc also supports creating PDF slides via LaTeX and HTML5 slides via Slideous, Slidy, DZSlides or reveal.js. These formats allow virtually full customization of the generated slides, including the use of JavaScript and CSS for HTML5 presentations.

Conclusion

We've been automating most of the preparation for our sprint review slides this way for almost a year now, saving an hour each sprint. If you're preparing slides with information from a system that exposes an API or prefer the text editor like I do, I highly recommend trying Pandoc out.