[Docs request] Workflow for working with academic templates

[drmowinckels]

I've been testing teaching using Journal templates for Quarto, but I keep hitting the same issue every time:
What is the best workflow for using a template, knowing you are likely to switch to another template at a later stage?

Academic publishing often leads us into several rejections from various journals, meaning the need to switch template.
But I have yet to find a workflow that I find particularly satisfying to recommend.

I usually start with recommending to quarto use template as this provides also a template.qmd to start filling in, often with useful links to journal publishing guidelines. This, however, forces the use of a sub-directory, and the need to either:

1. move _extensions folder to the project root for use with the main doc and possibility to add more extension + transfer the template yaml to your document and start adapting
2. copy your document content to the template.qmd and adapt the yaml + do the same for every new extension, overpopulating the the project with unnecessary sub-directories.

Having the template.qmd is so very useful to know what yaml options the template has or needs, but the subdirectory (though understamdably needed) makes a messy project.

When trying to show the second way of installing a template quarto install extension the project structure is nicely maintained, but there is not template.qmd to aid in yaml option settings. It requires exploring the root repo the template is in on github and opening the qmd there to see the tempalte. This is not so convenient.

Do you have any recommendations for how a workflow for this would look like?

[dragonstyle]

Thanks for the clear writeup of the workflow challenges! I think we originally envisioned two cases (which I think you will see leads to the sorts of challenges that you are outlining):

1. Starting a new article using a journal format (e.g. you know what journal you're targeting when you start). Use quarto use template and we'll use the current empty directory (or prompt if the directory isn't empty).

We currently enforce the empty directory (or new directory) in the use case because we a really just moving the complete repo contents into the local directory and we won't necessarily be able to resolve file conflicts in any sane way.

2. Adding a format to an existing article using quarto install extension. This really does merely install the format and doesn't provide any of the guidance that the template typically provides.

I think I originally underestimated the complexity / utility of the templates and their guidance, thinking that simply installing the extension and adding the format to the list would be enough.

One thing we could consider doing is still installing just the template when a user does a quarto install (e.g. provide a format derived unique name and provide a copy of that). Alternatively, we could offer to open to repo documentation after the install (since many of the repos have pretty solid READMEs with options (hopefully!)).

How much do you think it is helpful to have the template.qmd vs just perhaps offering to open the documentation for an extension?

[drmowinckels]

Everything you say makes sense. I can see that when starting to make the extensions you'd have (probably a little naive) idea that all that needs changing is the format. But we all know now that is not the case. Especially when changing to a template with sub-formats to choose from etc.

I think the idea solution would be to add the template qmd somehow. Now, I'm not particularly happy that it would end up in the root project, as this will ultimately lead to some messy project structure. I think there are a couple options:

• add template with unique format derived name to the root (easily discovered by the user, easy to delete when not needed, adding many templates creates a messy structure).
• add the template as part of the extension, with a message in the command line of the path where the template may be found so users can look at the options (does not clutter the project root, less easy to discover, less likely to be deleted).

I highly favour the second. Though that means the template would be part of the project (people are less likely to delete it), it does not create a messy project structure.

I'm not particularly fond of the idea of just pointing to docs, or having people navigate to the template.qmd in the originating repo, as I do teach novices and I see that as a potential confusion point. Like, I can already do that and am ok with it, but it add quite a but to cognitive load in learning to do this for novices.

[dragonstyle]

Ok, thank you for the detailed thoughts - we'll give this some consideration and see if we can make some improvement in the experience. I like the idea of including the template in extension, I think it would be great if we could somehow make it more discoverable.

[dragonstyle]

Adding some additional thoughts as I consider changes for 1.4:

• Copying files into the project roots (for example a template) when an extension is installed is simply too invasive dangerous, I think. I think it will also be immensely fragile (for example many templates in our journal repos refer to a bibliography file).

• I think the local copy embedded within the extension has the advantage of not requiring viewing external documentation, but I think will be very limiting (e.g. if you miss the message it will not appear again, the documentation might be more limited to prevent cluttering the extension directory with complete docs).

• The remote url for documentation and usage remains the most compelling thing for me, and trying to find a way to automate this and make it usable seems the best option. For example, if we offered to open the following URL following the installation of the elsevier format, I think this would be a great experience:

  https://github.com/quarto-journals/elsevier#elsevier

  Since this url documents usage, provides a preview, describes options, etc... The url approach would mean we could ultimately link to full fledged documentation that make using a template clear and easy, rather than attempting to solve the issue with local files.

As a start, I'm planning to add url support to extensions and add an offer to open the url post install - I'd like to see whether this provides a meaningful improvement in the experience before we crack open trying to solve it locally.