Converting documents to tutorials or templates through the UI

[fflorent]

It's possible though very technical to convert a document to a template or a tutorial: you have to make Rest API calls (PATCH /docs/{docId} with this body: {"type": "template"}, {" type": "tutorial"} or {" type": ""} if you want to convert back to a regular document)

It could be much more convenient, more user-friendly and more discoverable to allow changing the document type through the settings panel of the document.

[fflorent]

Here is a mockup proposal for the "Nature of the document":

Some notes:

• this field would be located at the "Document settings" pane;
• it should be localized;
• for the mockup, I used a regular <select> HTML element for simplicity, but it should in fact reuse the same components as the other fields above;
• When the value is changed, the document should be reloaded automatically so the changes take effet;
• I am not sure about the wordings;

[vviers]

Are there specific conditions that need to be met in order for a document to be turned into a tutorial or template ? e.g. can you make a tutorial if there is no GristDocTour table in your document ?

If so, we might need to think about helpful error messages :)

[fflorent]

e.g. can you make a tutorial if there is no GristDocTour table in your document ?

Hmm, I think so, so I would say no need for handling error or exceptional cases.

[lusebille]

As a user I would think it's a bit hidden to put that in the settings, or at least it's not enough , I may think common user journey could be. :

1. I know I want the file as a tutorial from the beginning and I want to choose that option when I'm creating the doc so when I click to 'Add new' I will have on the dropdown list ' Create a new tutorial ' or 'Create a new template '
2. I don't know firstly that my document could be a tutorial or a template but I realized later it could be useful (because I'm a Grist Genius whaou ) for me or my colleagues and I may want to share it so I. suggest adding on the dropdown list clicking on the share icon : 'Convert to a tutorial / Convert into template or Copy as a tutorial / Copy as a template [because I suppose in that case you may want to copy it'
3. I will add than me (Lucie) as a new user of Grist I was looking after a 'file' button with saving/export options but for now the closest iseems to be the sharing button

[fflorent]

Thanks for your feedback @lusebille!

I know I want the file as a tutorial from the beginning and I want to choose that option when I'm creating the doc so when I click to 'Add new' I will have on the dropdown list ' Create a new tutorial ' or 'Create a new template '

Unfortunately, at least as of today, there is currently a subtlety: you must first create a regular document and prepare your template or tutorial. Only once it is ready, you may convert it to a tutorial or a template. Also if you want to modify a tutorial or a template, you should first convert it back to a regular doc.

I know I want the file as a tutorial from the beginning and I want to choose that option when I'm creating the doc so when I click to 'Add new' I will have on the dropdown list ' Create a new tutorial ' or 'Create a new template '

Interesting. I would suggest doing that either in replacement of this issue or as a complement in another issue then, but it would be out of scope of the need as expressed at the beginning. Do you have any thoughts?

I will add than me (Lucie) as a new user of Grist I was looking after a 'file' button with saving/export options but for now the closest iseems to be the sharing button

Yeah, you make a valid point! If I understand correctly, you would have liked to find the "export" as a menu item of a "file" button. There is an UX improvement to make, these issues are related: https://github.com/gristlabs/grist-core/issues/754, https://github.com/gristlabs/grist-core/issues/951, and maybe https://github.com/gristlabs/grist-core/issues/540

Maybe we could create a meta-issue to track that? But also out of scope here (which does not mean it is not interesting!)

[dsagal]

BTW, it may be worth keeping in mind, as far as what's the common user journey, that very few documents are templates, and even fewer are tutorials. And few users would be creators of templates or tutorials, compared to all users creating Grist docs. On the other hand, these numbers will increase if this is made more convenient (but it would still be relatively uncommon).

[fflorent]

Working on this with @hexaltation

[hexaltation]

@dsagal @paulfitz @lusebille @vviers https://github.com/gristlabs/grist-core/assets/31125573/ec9e08d0-a31b-451a-ad5f-d2cf3acd3f8c Does the demo behind the link makes sense for you? If so I will make a MR according this behavior.

[lusebille]

@dsagal @paulfitz @lusebille @vviers https://github.com/gristlabs/grist-core/assets/31125573/ec9e08d0-a31b-451a-ad5f-d2cf3acd3f8c Does the demo behind the link makes sense for you? If so I will make a MR according this behavior.

I understand what is happening but could it be possible to have an anchor to the dropdown and not have this 'jump effect' when you're choosing a value ?

[dsagal]

Hi @hexaltation ! The demo makes sense. As far as the UI, I'd like to request a change. "Document Type" is not self-explanatory, and many users wouldn't know what it means. It would even be hard to figure out through experimentation.

So.... to make it clearer, I suggest instead of a dropdown, a button that opens a larger modal, with each option explained, like for Formula Timer, with the radio buttons in the modal. I suggest calling option "Template mode", and the button could be "Change type".

The explanations could be:

• Regular document: Regular document behavior, all users work on the same copy of the document.
• Template: Document automatically opens in fiddle mode. It is editable even to viewers, with the first edit causing a new unsaved copy of the document to be created.
• Tutorial: Document automatically opens with a new copy.

(The last part, I am actually unsure about, it may need a different explanation.)

At the bottom, there would be a "Change type" and "Cancel" buttons.

What do you think?

1. The description could still be "Convert the document", with the three options "Regular", "Template", "Tutorial", like you made. One minor comment here is to use a plain dropdown (as for "Python version used" e.g. here) rather than an autocomplete.
2. Once another option is selected, open a modal confirmation dialog, also similar to the one for "Python version used", but with a longer description (like for "Reload data engine" option)

[lusebille]

To discuss , here are the proposals : https://www.figma.com/design/wcpetFt6aOKzTszcvPPWLQ/%5B05%2F24%5D-Grist-Design?node-id=559-80548&t=SbtMMmgw2rANLbqL-1

[lusebille]

Ready from a designed point of view @hexaltation https://www.figma.com/design/wcpetFt6aOKzTszcvPPWLQ/%5B05%2F24%5D-Grist-Design?node-id=559-80548&t=1gSxqwNd6ZsiXdFO-1

[dsagal]

Design looks good -- thank you @lusebille ! I added some comments in Figma, to clarify the text and to point to how we show notification toasts.