docs(frontend): add performance tips section

[umut-sahin]

(closes /~https://github.com/zama-ai/concrete-internal/issues/772)

[bcm-at-zama]

Please, before adding new sections in the doc, let me sit a bit with @yuxizama, such that we define the architecture of files and doc. Then, we'll add the sections. Else, we keep adding files and files, and we add too much complexity

So blocking the PR for a moment please

[umut-sahin]

Sure, we don't have to merge immediately, but let's improve the content as much as we can. We can just move it to wherever when we are ready to merge.

[yuxizama]

It's very useful to have this kind of content for users! Thank you @umut-sahin
Regarding the architecture, I don't see any problem with this one being inside "compilation". However we're about to define some general doc objectives for Q3 with @bcm-at-zama , so we'll get back on this shortly.

[BourgerieQuentin]

That's a great start to have this page. I would change the ordering, or maybe several section:

Improve parallelism

• Tensorize
• Dataflow

Optimize tlus

• Reduce number of tlus
• rounding/truncate maybe merged with approximate, as it's a optimization of the rounding?
• p-error
• bit extraction
• complex operations
• modules

[umut-sahin]

I've grouped the tips by category 👍

[bcm-at-zama]

I've not read the content but at least, where the new file is is OK with what we've agreed with Yuxi. So, if you want to merge when I'm off, good with me (but have it reviewed by someone, obviously).

[bcm-at-zama]

Thanks a lot for this new documentation.

I have however a concern, which is that the new .md is very very long. I know from @yuxizama, and from our own experience, that we would like to have smaller .md's. We also wanted to try to keep a part of the doc for "simple" users, and some other parts for advanced users. I have moved eg some long & extensive part to "Explanation" part.

So I would maybe ask @yuxizama and @BourgerieQuentin what they think about this. In particular, we may consider

• splitting that into several md's
• and have an "Optimize tips" category on the left pane, instead of a single file

[umut-sahin]

I've split it in multiple files, let me know if you like it @bcm-at-zama 🙌

[bcm-at-zama]

Thanks @umut-sahin . Sorry, I still have a few concerns:

• I would not add this to where you've added it, but to Explanations; and I would add a short summary in the "easy part"
• some parts are not self contained, it's easy to fix

Let's have the opinion from @yuxizama before doing more changes.

[umut-sahin]

I would not add this to where you've added it, but to Explanations

To me, Explanations are for explaining how things work, like how things are done internally. These are not explanations.

and I would add a short summary in the "easy part"

I don't think we should split this to easy/hard. We need to have a place where users can see what they can do to improve the performance of their circuits, this is exactly that, grouped by performance considerations across different areas. It's a lot more organized than easy vs hard optimizations.

[umut-sahin]

These are in fact guides, more than explanations.

[bcm-at-zama]

and I would add a short summary in the "easy part"
I don't think we should split this to easy/hard. We need to have a place where users can see what they can do to improve the performance of their circuits, this is exactly that, grouped by performance considerations across different areas. It's a lot more organized than easy vs hard optimizations.

To me, our doc used to be too long and too explanative. Users don't want to read a book, they want short things that they can do. For long things, I would use the Explanation part. We used to have lengthy lengthy things, I have tried to simplify this.

[umut-sahin]

Each page is like single page already, we can't make it shorter. And keeping all optimization ideas grouped is a lot better in my opinion as users won't need to jump entire different sections of the doc.

[bcm-at-zama]

These are in fact guides, more than explanations.

'Guide' in the docs (C and CML) is more for deployment

[bcm-at-zama]

Each page is like single page already, we can't make it shorter.

To me, it's too long for the easy part. See what I have done eg for

* [Table Lookups basics](core-features/table_lookups.md)
* [Non-linear operations](core-features/non_linear_operations.md)
* Other operations
  * [Bit extraction](core-features/bit_extraction.md)
  * [Common tips](core-features/workarounds.md)
  * [Extensions](core-features/extensions.md)

I have tried to make them small and just about what the simple user need to know/do. The full info has been moved.

Let's @yuxizama dive in here

[umut-sahin]

'Guide' in the docs (C and CML) is more for deployment

Then they are not Guides, they are Deployment Guides. Saying Guides in the title and then implying Guides is only for deployment is certainly more confusing then using Guides for all kinds of Guides.

Plus, optimization is also important for actual deployment.

[umut-sahin]

To me, it's too long for the easy part. See what I have done eg for

Optimization is an advanced topic, I really don't think we should sprinkle some of it here and some of it there. Users can learn the library in the "easy" part, develop their application and when the time to optimize comes, they can read the "hard" part in one place to maximize their performance.

Lastly, if we split these tips across the docs, they can even miss some of the tips as they could only look for one part.

Anyway, I'll let @yuxizama and @BourgerieQuentin reply and then continue 👍

[BourgerieQuentin]

I'm aligned with @umut-sahin , I think splitting optimization tips across the documentation is a bad thing. The "easy part" should be simplest as possible just documenting features without any complexity, then a chapter regrouping optimization is a must have for me. It follow the development process, "make it works then make it fast". And I'm ok it's not explanations for me it should be a dedicated section of the documentation.

[bcm-at-zama]

And I'm ok it's not explanations for me it should be a dedicated section of the documentation.

We don't want to add a new section in the documentation too often. The main sections is decided by @yuxizama, has some common names with other products etc.

[bcm-at-zama]

We've decided for

Short optim part: in Execution/Analysis
Long optim part: in Guide

[yuxizama]

Hey @umut-sahin
Thanks for the update.

Before merging this, I just have 1 last thing to add:
Could you add a 1-sentence summary at the beginning of each doc, starting with "This document explains/provides/introduces .....". It gives readers an overview of what they will see in the doc.

You can find such examples in all the TFHE-rs doc, the "Get started" part of Concrete doc and part of CML and fhEVM doc. It's a format that I'm trying to use for all the docs.

Besides that, the rest of good for me.

[bcm-at-zama]

I guess this has not been completely modified, to take into accounts the previous reviews, right?

For the summary, I am quite happy: it gives a not too long overview, with some actions (ie, options) that the user can try

[yuxizama]

I proposed to shorten the titles, otherwise it looks very long on the side menu. With the title shortened, it makes better sense with the introduction summary in each doc.

[bcm-at-zama]

Looks good to me, thanks a lot @umut-sahin

[bcm-at-zama]

(some compliance problems, however)