Onboarding Docs for new users

[virgile-dev]

Feature Request

Is your feature request related to a problem or unsupported use case? Please describe. Some users are not super familiar with block based structured editors, slash commands, markdown etc. Docs is super confusing for them.

Describe the solution you'd like For new users instead of having no docs. Why not display a doc which content can serve as tutorial. Where there would be examples of all text blocs. Instructions to play around etc.

Describe alternatives you've considered Adding a tooltip on the docs editiing page. When you click on it you get a modal that explain the features of the editor. Like in the pad. But I feel it's less interactive.

Discovery, Documentation, Adoption, Migration Strategy Notion isn't empty when you join. You can play with template to get started.

[virgile-dev]

Add an item to have the user try the AI features.

[virgile-dev]

Here the content for the page : https://docs.numerique.gouv.fr/docs/2e71cbaf-2251-4442-a540-7dca099a9b12/

The idea is to create this doc for each user. It will be a private doc with restricted access. They'll have edit rights on it.

For existing users if we can pin it to the top of their list it could help them advance their knowledge of the tool. (Not sure about this one).

[virgile-dev]

In addition to having this doc created for each user. It would be great to feature it in the welcome email each user receives at registration.

[rvveber]

I'm currently implementing this via frontend API calls for openDesk. But i'm not happy with how it turns out.

Notes about implementation

The content of the doc is presumably in a base64 encoded binary YDoc(?) format. Its not documented, nor straight forward, on how that format is encoded. Atleast i couldn't find many hints.

So what i'm doing, is: capturing the base64 content of a document when it is saved and statically sending that, to update the content of a doc. I can't really think of a better way, since the block-format is more complex than markdown/html. But it doesn't feel like the ideal solution. @AntoLC @sampaccoud Any ideas?

Reduce api-overhead

In frontend code, we have many useDoc functions that aren't universally useful or incomplete. E.g. createDoc from useCreateDoc is not able to create with content, so another updateDoc has to be used. Maybe we could refactor this into a single service that offers full CRUD? And while thinking about this, why stop there, maybe we could eliminate the effort that goes into this, by using a tool that generates the API client from the swagger doc for us? If it works, it could save some expensive maintenance and mental overhead. I think it would accelerate development alot and uncover inconsistencies in the API faster.

Some tools that i found are: https://github.com/swagger-api/swagger-codegen https://openapi-generator.tech but there seem to be more

[virgile-dev]

Hey @rvveber I discussed this with @sampaccoud yesterday. He thinks a better way to do this would be using the upcoming #570 Duplicate API endpoint It needs to be extended to take into account the author change. Maybe you can have a look

[rvveber]

@virgile-dev I like this idea. But it is not solving the problem. The initial document that is to be duplicated, still would need to come from somewhere.

And that somewhere would need to have the doc in current and future languages.

[rvveber]

@virgile-dev @sampaccoud @AntoLC What about this solution:

1. We create a template for this - perfect source, can be managed from the backend already & supports API/programmatic access without the need for YDoc format
2. It can be html or markdown, composed of $t{translatable strings}
3. On the frontend, whenever we own 0 documents,
4. We fetch the tutorial template from the template endpoint
5. Translate the template
6. Try parse HTML/Markdown to YDoc (functions already exist)
7. And create the document via API

• Ideomatic, we use existing template functionality
• Customizable, tutorial template can be customized via backend or API
• No need for the YDoc to already exist somewhere (it would be complicated to programmatically or by-hand edit the YDoc; format conversion; inaccessible to i18n; not to mention authentication/authorisation and even identifying the source doc)
• Language agnostic, one template, multiple languages
• YDoc changes are created as a whole and with correct author information, avoids potential bugs

[rvveber]

Actually, why are we not storing translations in the backend, just like we do with other data(configs)?

If we did, we could also translate in the backend and therefore could create the doc from the template on user-sign up. Independently of the frontend and API.

We could re-create it when necessary on delete event of a doc, no? We could even re-create it instantly in the correct language, when the language (if it was synchronised) is changed. We could also allow for manual changes to the translations in the django backend (if we add them as entity) that get reflected in the frontend.

Frontend would just pull the translations via API, cache them and plug them into i18n. Then both backend and frontend would have access to the same translations.

Customizing tanslations in the scope of K8s would be possible, without patching and rebuilding the image. Translations would not be statically compiled and could just be placed into the backend container, even at runtime.

[virgile-dev]

@lunika after giving this some thought when a user first logs in on Docs. I'd like for him to see 3 docs.

• The Docs user guide (a doc that's shared with him), the instance admin can chose the id of the doc he wants to display there (in an env variable or something, by default there's nothing). It should be pinned as favourite.

-> On our instance it would be this one: https://docs.numerique.gouv.fr/docs/335e43b5-9e16-4798-a0b4-912e44c7135e/

• Templates library a doc where we propose a series of templates to users. It should be pinned as favourite

-> on our instance that doc would be : https://docs.numerique.gouv.fr/docs/6de1e458-088f-4c71-a58d-b8606e7b1b64/

• Sandbox (a doc that's created for him where he is the owner) where he has checklist of stuff he can do to learn docs (like mentioned here). Same here the instance admin will provide the id of the document that will be used to duplicate the doc for the user

-> on our instance that doc would be : https://docs.numerique.gouv.fr/docs/99d26478-b377-48ee-a2ba-f172898146fb/

By defaults these env variables are empty