I'm really fed up with this damn document

[yourouchour]

The current documentation lacks the necessary descriptions such as show, set, function, etc. Some of the considerations for defining a function, such as not being able to modify global variables, are not mentioned at all. :( The documentation needs to get better.

[SillyFreak]

I feel your frustration; we’re aware that the documentation needs improvement. See e.g. here:

Could we have more examples (including straightforward ones) in the documentation?

It’s a fact that the current documentation is not great for beginners and we’re aware of it. We want to put greater focus on creating better introductory-level material in the near-ish future. We’ve noticed that some people love the docs and some don’t like them at all and the distinction is typically whether they are experienced programmers or not. That’s something we need to improve on: In part with tweaks to the reference, but primarily with better tutorial and guide-style documentation.

there are probably some other responses in that thread you may be interested in, in case you want some more context of the existing discussion.

Re the “in the near-ish future” in the post I linked: the plan is to migrate the docs themselves to Typst, which requires some more work on Typst’s HTML export. Once these two steps are finished, I’m fairly confident that doc improvements will come more into focus, maybe/hopefully also in terms of community contributions.

---

Re your concrete criticisms:

@yourouchour

lacks the necessary descriptions such as show, set

I assume you have seen Formatting – Typst Documentation; do you see any specific things missing from it? I’ll add a first thing: the only show rule there is for text, which is not even recommended most of the time (this is addressed on the next page of the tutorial though), and there’s no show-set example, even though that’s super important in practice.

@yourouchour

function, etc. Some of the considerations for defining a function, such as not being able to modify global variables, are not mentioned at all. :(

Functions in general are at Scripting – Typst Documentation, but yes, a detailed description what modifying a variable in Typst can and can’t achieve is necessary.

---

fwiw, the shortcomings mentioned in the previous thread were as a consequence reported on Github and promptly improved, so if you have concrete suggestions, please bring them. And if you have concrete questions, please ask them here on the forum.

[rfarhaz]

I also have a similar issue in the formatting section and in the text function that there should be an explicit example of how to use custom fonts locally. It is missing. There is a statement but I think an example would do justice.

[LRoInT]

Some functions should can be found easily, like symbol function. First time I read the big Symbol. Beacuse it is more easilier to found but it doesn’t have any information about symbol function. You can say it is a problem about my ability, but change it’s site can be better.

[maucejo]

I have the opposite feeling. I find the doc well written, although it could be improved (e.g. query section). I found many answers in the descriptions of the functions (such as the font argument of the text function).

For people coming from LaTeX or having some knowledge in programming language, Typst is quite easy to use.

An efficient way to learn Typst is to read the source code of Typst packages. I have learned a lot by doing this.

Don’t let your frustration to stop you using Typst

[Sergio]

I feel I’m a counterexample on the programmer/non-programmer divide.

I am an ocasional programmer with experience in a bunch of languages and even more experience in reading and parsing tech documentation, and I still have my gripes with parts of the docs.

Don’t get me wrong: I love that it is very systematic and easier to skim than LaTeX’s. But the two points I sometimes struggle with are:

• Examples. Some parameters take very specific values (e.g. strings that expect a specific format) and it sometimes takes too many links and a bit of guesswork to figure out how things are supposed to work. I find that happens most often to me with complex APIs like cetz, but also happened to mr recently while trying to understand the format of a function for filter. Many more examples for table configs (or a sort of formatting assistant for it) wouldn’t hurt either.
• It is sometimes tricky to find the right docs when you know what you want but not how Typst calls it. I seem to remember I struggled recently figuring how to draw an arc (part of a circle) because I wasn’t searching for the right word.

But this is just anecdotical. As usual, the groundwork is already amazing!