We Converted our Documentation to Quarto - posit::conf(2023)
Presented by Melissa Van Bussel Elevate your Quarto projects to new heights with these practical tips and tricks! "Wiki", "User Guide", "Handbook" -- whatever you call yours, we converted ours to Quarto! A year ago, my team's documentation, which had been created using Microsoft Word, was large and lacked version control. Scrolling through the document was slow, and, due to confidentiality reasons, only one person could edit it at a time, which was a significant challenge for our team of multiple developers. After realizing we needed a more flexible solution, we successfully converted our documentation to Quarto. In this talk, I'll discuss our journey converting to Quarto, the challenges we faced along the way, and tips and tricks for anyone else who might be looking to adopt Quarto too. Slides: https://melissavanbussel.quarto.pub/posit-conf-2023; Code for slides: https://github.com/melissavanbussel/posit-conf-2023; My YouTube: https://www.youtube.com/c/ggnot2; My website: https://www.melissavanbussel.com/; My Twitter: https://twitter.com/melvanbussel; My LinkedIn: https://www.linkedin.com/in/melissavanbussel/ Presented at Posit Conference, between Sept 19-20 2023, Learn more at posit.co/conference. -------------------------- Talk Track: Quarto (2). Session Code: TALK-1140
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
My name is Melissa Van Bussel, and I'm an analyst at Statistics Canada, which is the official statistical agency of Canada. Today, I'll be talking about how my team converted our documentation to Quarto, and doing this conversion was definitely a journey.
Not all journeys go according to plan. But before I get into the details of how we did this conversion, I want to first start by sharing a story about another journey that didn't go according to plan.
I want to take you all back to the DIY era of the COVID-19 pandemic. During that time, my housemate and I decided to build our own outdoor couch. We found this template online, which looked doable. We bought the wood from the blueprint and coughed up the $85 Home Depot delivery fee because we didn't have a car that would fit the wood in it.
But as soon as we got the wood delivered, we quickly realized that the saw we had wasn't exactly going to cut it. So we needed to borrow a better saw from a family friend. This made everything so much more efficient, and we managed to finish building the couch. Or so we thought.
It turns out that the instructions that we'd been following were actually only for the part of the couch that was missing an arm. We had only purchased half of the wood that we needed. So we needed to head back to Home Depot, and we bought the rest of the wood that we needed. There was just one problem left. We still didn't have a car that would fit all the wood in it.
And we had paid that $85 delivery fee the first time, but we really didn't want to pay that again. So we borrowed a truck from a friend in order to get the rest of the wood home. Once we had the right tools and all the resources and help that we needed, we were able to successfully finish building the couch.
This journey full of unexpected challenges is very similar to the journey that my team had when converting our documentation to Quarto. Today, I'll share that journey with you, as well as the challenges that we faced along the way. I'll also share some tips and tricks that we used, all of which are applicable to any kind of Quarto project.
Context and the problem with Word
I'm going to start by providing some necessary context. I work on a team at Statistics Canada that publishes statistics related to education in Canada. There's a lot of domain knowledge and subject matter, as well as methodological concepts that need to be documented somewhere.
This leads to a very important distinction in the title of my talk. When I say the word documentation, I'm not talking about our package documentation. I'm talking about documentation that defines terms like these. So it's really the subject matter documentation and not the package documentation. I'm talking about the sort of information that somebody might put in a wiki or on Confluence or something like that.
Whatever you call yours, we call ours a user guide. And for us, it was previously stored as a 120-page Word document. Scrolling through this document was slow, and only one person could edit it at a time, which was a significant challenge for our large team. Our version control was limited to the track changes feature in Word, which made it pretty challenging to follow updates over time.
After last year's conference, we discovered Quarto, which would address those challenges that we had been facing with Word. When we started this conversion, though, we were all total beginners with Quarto. This meant that in order for us to effectively complete this task, we would need to use the right tools.
Tools for converting and formatting content
When you're working with Quarto, there are so many tools that you can use to make your life easier. If you're looking to convert existing text to Quarto, a good first step is to convert the text to Markdown first if it's not already in that format. We used the Pandoc convert function from the R Markdown package to automatically convert our Word document from Word format to Markdown. This provided us a really great starting point.
Although this was a great starting point, it was still just a starting point. There was still a lot of formatting changes that we needed to make. In order to make this part of the job easier, we set up custom keyboard shortcuts in our IDEs. For example, we set up a shortcut that made it a little bit easier to convert URLs into valid Markdown links.
If you're using RStudio as your IDE, you can also set up code snippets, which are a great way to automate code insertion for anything that you find yourself typing out very frequently. This is great for when you want to use some of the cool Quarto features that take a little bit longer to type out.
I really recommend checking out Tom Mock's GitHub gist that contains code snippets that are very useful for working with Quarto. Those code snippets are provided for both RStudio and VS Code.
For any syntax that's a little bit trickier to type out, there are ways to avoid doing things manually. Personally, I find the syntax for Markdown tables to be extremely finicky. RStudio's Visual Editor comes in great handy for this, or you can also find similar tools online if you're using different IDEs.
For situations like these, Generative AI is another great option. Both ChatGPT and GitHub Copilot have a pretty decent knowledge of Quarto syntax, but an even better understanding of HTML and CSS. You can use Generative AI for a variety of use cases, but you'll find it particularly helpful for making your Quarto projects more aesthetic. If you're looking to use these tools, I've got a video on my YouTube channel that explains how to use ChatGPT and GitHub Copilot as an R programmer.
Version control and publishing
Once you're done with creating the content, there's something that you can do to make maintaining the content easier as well. You can use Git for proper version control, and you can use either GitHub Actions or GitLab Pipelines to automate the publishing of your content. This will make it so that every single time you make a commit using Git, the published version of your content will be automatically updated without you having to do anything.
I promise that this is much easier than it sounds, and I've got videos on my YouTube channel that give examples of Quarto pipelines using both GitHub Actions and GitLab Pipelines. Or if you prefer to avoid the whole pipeline thing altogether, and you're just looking for somewhere to host your Quarto content for free, I've also got a video that explains how to use Quarto Pub to publish a website in under a minute.
Getting help from the community
There are so many great tools for working with Quarto, but there are probably still going to be some times when you need a little bit of extra help. There's probably going to come a point where you want to do something and you don't know how to do that thing. Whenever that happens, you can ask the R community for help.
When it comes to asking Quarto questions, there's an order of operations that I like to follow. Of course, you should always start by checking the Quarto documentation and googling your problem to see if somebody's already made a video, a blog post, or posted on Stack Overflow about it. But if you can't find what you're looking for there, you can also reach out to your colleagues or friends, including the ones you make while here at Conf. You can also reach out to your local R user group or your R-Ladies chapter, if you have one.
In fact, if there's anyone in the audience from Ottawa, the R-Ladies Ottawa chapter will be having our first event in three years, coming up next Tuesday, September 26th.
In our case last summer, though, we were among the first to be using Quarto in our area, which meant that we sometimes needed to seek help using other avenues. Twitter is a great place for this, especially if you use the hashtags RStats and QuartoPub. For example, I tweeted this, asking if there's a clever way to render Quarto documents to PDF if the HTML version contains GIFs. Within an hour, someone had responded to my question, explaining that there's a way to make content visible or invisible, depending on the format of the output.
Another great place that you can ask your Quarto questions is by using the Q&A feature on the discussions portion of the Quarto CLI GitHub repo. This is where the development for Quarto happens, and when you post a question in the Q&A here, it might be answered by a member of the R community, or maybe even a member of the Quarto development team itself. Personally, I've found the Q&A feature to be an incredible resource.
There's been times where I've been stumped on syntax for multiple days, and I feel just about ready to give up. But then I post the question on the Q&A, and I'm able to get an answer within the same day.
There's been times where I've been stumped on syntax for multiple days, and I feel just about ready to give up. But then I post the question on the Q&A, and I'm able to get an answer within the same day.
For example, we needed to create a bilingual Quarto website that would allow the user to switch between English and French. To do this, we created a Quarto project that had an English folder and a French folder with identical file structure. Using the Quarto documentation, we were able to find a way to create a toggle that would allow the user to switch between the two languages.
The only problem was that when the user would click the button, it would take them back to the home page rather than displaying the current page in the opposite language. We asked about this in the Quarto Q&A, and it was suggested that we use JavaScript to create a button that would modify the URL when clicked. After following an example that was provided in the comments of that Q&A, we were able to successfully create this button, and we now have a fully bilingual Quarto website.
Feature requests and shaping Quarto's future
As you become more and more advanced with Quarto, you might find yourself asking questions that are actually unanswerable. What I mean by that is that there might be features that you're looking for that aren't currently implemented in Quarto. After all, it is still pretty new.
If this is the case, there's a good chance that someone from the Quarto development team will comment on your Q&A indicating that this is the case, or they might suggest a clever workaround instead. You can also check to see if there's already been a feature request for whatever you're trying to do, and if not, you can create one yourself.
Personally, I find this to be one of the coolest things about using Quarto, especially at this point in time. Even as an end user of Quarto, you could have the opportunity to help shape the future of Quarto.
Even as an end user of Quarto, you could have the opportunity to help shape the future of Quarto.
Getting colleagues on board
Once we had a working first draft, it was time to share our project more broadly with others. This is where we faced our third challenge, and where you're likely to face a challenge too. Although you might be super passionate about Quarto and confident in its potential, it is still a pretty new product, and not everyone is going to be on board on day one.
Getting that support for Quarto can be challenging, and the approach that you take may differ depending on your target audience. With management, a good strategy is to show, not tell. Rather than starting a conversation about Quarto, create a cool project using Quarto that will wow people. When someone inevitably asks you how you made it, this is when you can talk about what Quarto is.
Depending on your workplace, you may have the additional challenge of Quarto not currently being on the list of installable software. In our case last summer, we didn't have access to a version of RStudio that came prepackaged with Quarto. Instead, we needed to use VS Code as our editor while we waited for our version of RStudio to be updated. Another option is to use Rocker, which is a Docker image that comes prepackaged with Quarto.
In order to get your colleagues on board with Quarto, I highly suggest creating templates that you or anyone else can use as a starting point for their project. Not only is this going to prevent you from needing to reinvent the wheel every time, but it'll also reduce the barriers that others might face when trying to learn a new tool. You can either start with a pre-existing template, for example from the awesome Quarto repo on GitHub, or you can create your own. For example, I created this Statistics Canada theme for the Reveal.js format.
For any colleagues who don't have Git or Markdown experience, a great way to enable collaboration is to use the report issue feature on your Quarto projects. With just a single click of a button, a new issue can be created on the project's GitLab or GitHub repo, and the necessary changes can be described in plain text using a what-you-see-is-what-you-get type of text editor. This then makes it very easy for the developer to go in and copy-paste the modifications that need to be made with little to no modification on their end, allowing for effective collaboration across the board.
And finally, you can also enable Word and PDF formats for any end users who might prefer those formats over HTML.
Outcomes and adoption at Statistics Canada
Once we had the right tools and all of the resources and help that we needed, we were able to successfully convert our user guide from Word to Quarto, and we now have documentation that feels amazing to developers and users alike. Eric, who's a developer, appreciates how easy it is to automatically generate our documentation in three different formats using just a single commit. And Sylvie, who's an end user of the documentation, appreciates that Quarto websites are easy and pleasant to use, and that creating an issue whenever there are typos is straightforward.
At Statistics Canada more broadly, Quarto is now a pretty popular tool. Not only has my team continued to use it for any new projects that we start, but other teams have started to adopt it as well. For example, the website for Statistics Canada's R and Python User Group, or RPUG for short, was recently converted from Hugo to Quarto. Training resources for teaching people about R and Databricks have also been created using Quarto, and at the individual level, analysts have started using the reveal.js format to create stunning presentations.
I hope that with these tips and tricks, you're able to have a successful project, whether that's adopting Quarto or completing your own DIY. Thank you.
