How about a task force to generate a better documentation?

General
1

Hello,

I started to learn Typst not long ago, a few weeks to be precise. I found that I’m part of a (growing?) group of users frustrated with the documentation. Sometimes we get angry (like this guy), but in most of the time (as in these examples: 1, 2, 3, 4) we just want to find necessary and more complete information in the official site, which is expected to be the main source of information.

I found myself regularly spending several hours on the forums, github, searching on the Internet or even trying AIs and not being able to find good solutions, sometimes no solution at all.

At the same time Typst is in its first baby steps (version 0.13.1) which means, at least for me, I should not expect to find solutions for everything and lots of them will necessarily be temporary and “ugly”. However, both Typst and its community have grown enough to start demanding some kind of task force to decide about features details, standardization and most of all to produce a better documentation followed by guides and tutorials which should be easy to find through Typst site itself.

For instance, yesterday I found in the forum the Typst Examples Book which seems to be very good, and its organization seems to be way better then the official doc. If I may, I suggest this book to be added to the guides page.

Now, going back to the frustration. At least for me what made me frustrated was the expectation of finding docs similar to those of programming languages and their libraries. As I could understand of Typst one of its main feature, that stands out over LaTeX and similar softwares, is the possibility to use real programming. I mean Typst is much more than a markup language. Maybe it is not a full programming language as well, but it is in some middle ground between them. I would say it is closer to a programming language. The current documentation already presents Typst closer to a programming language, unfortunately lacking information, examples and maybe a better approach.

That said, I’d like to suggest a collective effort to update or produce a documentation similar to what we find in Rust docs, for example. I mean with extensive information and examples. Several users already show deep knowledge on how Typst works currently. Their collaboration shall be priceless.

Furthermore this task will surely take some time and demand a huge effort, however, Typst itself is going to benefit from it as standards become easier to be defined and tracked, and adding new features may be guided by some standard that was thought before.

Before finishing I’d like to apologize for the text wall and some misunderstandings or false claims I may have done. I’m still quite new to Typst so I can’t know, for now, how much of what I suggested already exists or not and if some of the complaints was already addressed.

Thanks!

8 Likes
2

Hi

Also for information, here are a comments with links to mannnnnyyys discussions over discord, github, etc…

1 Like
3

For your information, Discord → forge → Documentation has been created recently.

  • To avoid conflict work
  • To help people (with or without rust experience) find the right file to edit
  • To call for others to help review docs
  • To discuss other possiblities (article rearrangement, migration to typst, translation, etc.)

There are many things to be done: Topics tagged documentation and GitHub search: is:open label:docs.

I think the first step is drafting a meta docs on improving docs:

  • how are docs organized
  • how to link to other pages (e.g., [counter] and$counter)
  • special markups (e.g. `{none}`)
  • the syntax of examples (>>>), and their preamble (#set page(height: auto, width: 240pt, margin: 15pt))
  • style guide (line wrap at 80)
  • CastInfo in typst_library::foundations - Rust
  • …

I guess typst/typst | DeepWiki is able to answer most questions, but a human documentation would be better.

2 Likes
4

I will just leave this here: About | Divio Documentation It is an amazing guide how to write great documentation for software. In essence a documentation system needs four different resources to facilitate learning at different levels:

  • Tutorials (learning oriented)
  • How to guides (problem oriented)
  • Explanation (understanding oriented)
  • Reference (information oriented)

In my opinion Typst has a very good references.

There are some great explanations in Laurenz’s Blog but there should be more resources like that. It would be nice if experienced Typst developers would publish e.g. how they go about and patch issues, how does the query engine work, etc…

The tutorial in the docs is ok but it is only one example. It would be nice if there were a few more tutorials how to create some standard categories of documents: CV, booklet, datasheet, invitation with some fancy graphics, project report.

The how to guides are essentially missing. This is the FAQ that we need. How do I put an image in a page corner? How do I use a custom font? How do I center an image? Essentially everything that is asked for in the Discord all the time.

When you create resources like that please also remember to state the version of Typst you use. It is all too common to find old tutorials that don’t work in the current version.

4 Likes
5

In case anyone else remembers it being mentioned Discord or is otherwise wondering about the relation between Divio’s documentation system and Diátaxis – it seems they’re forks.

Here are their repos: Diátaxis, Divio; Both repos start in March 2020 with Commit e67865a1 authored by Daniele Procida and contains Divio branding. The history diverges after 12d00748 in September 2020; the Divio branch has more commits by Daniele Procida until April 2021 and their final commit changes the copyright notice to “Divio Technologies AB”. On the other repo also in April 2021, Daniele Procida changes the branding and launched the Diátaxis site.

So it seems both are just legitimate forks, none stealed from the other. Daniele probably exited the company, and preparations were made that both parties could continue using the content. Diátaxis seems to have had more activity; most changes to Divio’s version since the fork have been typos or technical, not updating content.

1 Like
6

I believe in some ways hosting this forum and a Questions category was meant to fill in the gap for the documentation. I haven’t looked at the readership statistics, but I believe it has helped many people so far!

I think it would be very hard to write a “definitive” guide to do X or Y, because the package ecosystem rotates completely every few months or so. The forum is meant to help by answering small questions, so there is less to information “maintain”.

If there are N users, there will be N+1 special cases to deal with… everyone wants something custom.

I think someone mentionned an ongoing work to refactor how the docs are generated? It would help lower the contribution difficulty threshold for sure.

2 Likes
7

Actually divio was launched before Diátaxis!. See open source license? is it thought as a collaborative project? · Issue #14 · evildmp/diataxis-documentation-framework · GitHub

8

Yes, maybe that wasn’t explicit enough. The repo contained Divio branding from the first commit, and it wasn’t removed until after the fork – which presumably happened when the original author left the company. I only wanted to point out that 1) there’s nothing nefarious going on (which it looked like to me at first) and 2) the Diátaxis repo is the one more actively maintained.

9

Sure thing, but now we can see what problems arise often and address them directly in the docs. Treat the forum and Discord as a feedback for what is missing.

If anyone wants to start I suggest starting with: How to place an image in the background of a page?

3 Likes