Add guidelines for the description field

[rwmpelstilzchen]

The description field is defined as follows:

• description: A short description of the package. Double-check this for grammar and spelling mistakes as it will appear in the package list.

A quick glance on the said package list reveals some inconsistencies. In order to help Typst Universe communicate professionalism and consistency even better, I suggest formulating guidelines that unify the way descriptions look. These should not be hard-set rules but guiding principles that cultivate better ways for package- and template authors to explain what their contributions are for. Practically, I think this should be done in three places:

• First, the submission guidelines section of the readme. This pull request offers a preliminary draft for such guidelines.
• Secondly, warnings by the Typst package check bot if something is automatically detected.
• Lastly, if the contributor doesn’t change the description and the individual case justifies that, human feedback is the last resort…. IIUC, @elegaanz is our friendly Universologist 😉. If you all think this is a good idea but it’s too much of a hassle, I don’t mind proposing polite suggestions to reword descriptions whenever pull requests are in if needed.

I don’t think contacting past contributors is a good idea, but when new versions of existing packages and templates are submitted in case that’s needed it’s possible to ask the contributors if they want to reword the description.

I took the liberty of changing the description field of the package example and the template charged-ieee in the readme (but not in the actual packages) because this is just a draft.

What follows is some points I think worth considering, in the order of proposed guidelines in the pull request. My thoughts are written after the horizontal line in each subsection (tl;dr: I think succinct, minimalist, short and sweet descriptions are the best — less is more). The rewording suggestions within each subsection tackle the point in question individually; some descriptions can be changed with respect to more than one point, but I wanted to keep it focused. The choice of packages and templates that serve as examples in the tables below is arbitrary and not done to criticise specific cases; I just copied and pasted the first packages I found that demonstrate the point under discussion 🙂

Long descriptions

Some descriptions are extremely long; for example:

Name	Description
pintorita	Package to draw Sequence Diagrams, Entity Relationship Diagrams, Component Diagrams, Activity Diagrams, Mind Maps, Gantt Diagrams, and DOT Diagrams based on Pintora which is heavily influenced by mermaid.js and plantuml.
flyingcircus	For creating homebrew documents with the same fancy style as the Flying Circus book? Provides simple commands to generate a whole aircraft stat page, vehicle, or even ship.

---

Long descriptions are not doing the reader any favour in being over descriptive. I think there should be a hard limit of 100 characters at most; maybe even less (see this, where the limit is of 70–75 characters). At any rate package/template authors should be encouraged to maximise the content:length ratio; most packages and templates can and should have descriptions which are 50 characters or less, consisting of well-chosen words.

The above can be reworded as:

Name	Description
pintorita	Draw diagrams with a Pintora-like syntax
flyingcircus	Documents in the style of the Flying Circus book

Explicit reference to Typst

Some packages and templates have an explicit reference to Typst; for example:

Name	Description	With ‘Typst’?
cades	Generate QR codes in typst.	yes
bookletic	Create beautiful booklets with ease.	no
letter-pro	DIN 5008 letter template for Typst.	yes
minimal-cv	A clean and customizable CV template	no

---

Context is king. There is no reason for this redundant information, as Typst Universe contains… well… packages and templates for Typst. There is reason for such an reference in the description of the package or template in their Git repositories, but this is completely unrelated: descriptions there and here don’t have to be identical, since here we have context that’s absent there.

The above can be reworded as:

Name	Description
cades	Generate QR codes.
letter-pro	DIN 5008 letter template.

Full stop.

Some packages and templates terminate the field with a full stop while some do not; for example:

Name	Description	With a full stop?
umbra	Basic shadows for Typst	no
suiji	A high efficient random number generator in Typst.	yes

In fact, the readme itself is not consistent:

⋮
description = "An example package."
⋮
description = "An IEEE-style paper template to publish at conferences and journals for Electrical Engineering, Computer Science, and Computer Engineering"
⋮

---

I think terminal full stops are unnecessary and should be avoided. They create visual clutter, and the description field is not running text. As the packages are already delimited typographically, full stops don’t have a delimiting function either. Compare the following grocery list:

• Fruits.
• Vegetables.
• Tahini.

with this one:

• Fruits
• Vegetables
• Tahini

The latter is much more readable.

‘(A) package/template (for/to)’

Some packages and templates have the words ‘package’ or ‘template’, respectively, in the description; for example:

Name	Description	Type	With ‘paper’ or ‘template’?
game-theoryst	A package for typesetting games in Typst.	package	yes
curryst	Typeset trees of inference rules.	package	no
casual-szu-report	A template for SZU course reports.	template	yes
basic-resume	A simple, standard resume, designed to work well with ATS.	template	no

---

I think having these words is redundant, and it’s better to communicate directly what the package does or what the template is for, without stating they are a package or a template in the description text:

• The fact they are either is obvious from the context of them being listed in Typst Universe.
• The distinction between the two should be communicated structurally and visually, not with an explicit word (‘package’ or ‘template’) that contributes little to the content. See the next subsection for how they are differentiated linguistically in the proposed guidelines.

The above can be reworded as:

Name	Description
game-theoryst	Typeset games in Typst.
casual-szu-report	SZU course reports.

This is closely related to the next subsection (both make the same guideline in the pull request).

Linguistic form

The corpus of package descriptions demonstrates uneven situation with regard to syntactic structures; for example:

Name	Description	Form
wordometer	Word counts and document statistics.	standalone nouns
polylux	Presentation slides creation with Typst	deverbal nouns
blinky	Typesets paper titles in bibliographies as hyperlinks.	present-tense verb
scrutinize	A library for building exams, tests, etc. with Typst	noun with adjunct
pyrunner	Run python code in typst.	imperative verb

Templates tend to use nominal forms more often.

---

I think we should treat packages and templates differently here. While I said above that using the words ‘package’ and ‘template’ should be avoided as they contribute little, I do think different linguistic forms suit each of the two better.

With packages — which allow the user to do things in their document — adopting the Linux kernel guidelines and using the imperative mood seems most suitable. For example, the above can be reworded as:

Name	Description
wordometer	Obtain word counts and other document statistics.
polylux	Create presentation slides with Typst
blinky	Typeset paper titles in bibliographies as hyperlinks.
scrutinize	Build exams, tests, etc. with Typst

With templates — which provides the user with ready-made moulds for documents of different types — I think that standalone noun phrases that describe the type of document provided by the template are the most suitable. Examples of this form include:

Name	Description	Type of document
classy-german-invoice	Minimalistic invoice for germany based freelancers	invoice
fh-joanneum-iit-thesis	BA or MA thesis at FH JOANNEUM	thesis
knowledge-key	A compact cheat-sheet	cheat-sheet

This way, the following

Name	Description	Form
invoice-maker	Generate beautiful invoices from a simple data record.	imperative verb
g-exam	Create exams with student information, grade chart, score control, questions, and sub-questions.	imperative verb
wonderous-book	A fiction book template with running headers and serif tyography	noun (‘template’) with adjuncts
meppp	Template for modern physics experiment reports at the Physics School of PKU.	noun (‘template’) with adjunct

can be reworded as

Name	Description
invoice-maker	Beautiful invoices generated from a simple data record.
g-exam	Exams with student information, grade chart, score control, questions, and sub-questions.
wonderous-book	Fiction book with running headers and serif tyography
meppp	Modern physics experiment reports at the Physics School of PKU.

Languages other than English

Some descriptions are in languages other than English; for example:

Name	Description
cumcm-muban	为高教社杯全国大学生数学建模竞赛设计的 Typst 模板
minerva-report-fcfm	Template de artículos, informes y tareas para la Facultad de Ciencias Físicas y Matemáticas (FCFM).
roremu	日本語のダミーテキスト生成（Lorem Ipsum）

---

Linguistic diversity is great, and some packages and templates are indeed language-specific. I think it’s best if Typst Universe supports multilingual entries, and the user can choose their preferred language(s). If there is no plan to do so in the near future, maybe it’s possible to have a temporary workaround: bilingual descriptions are welcome with a certain structure (say ENGLISH | ADDITIONAL-LANGUAGE).

With this structure roremu’s description can be reworded as:

Name	Description
roremu	Blind text (Lorem ipsum) generator for Japanese | 日本語のダミーテキスト生成（Lorem Ipsum）

Character-limit restrictions should be doubled, of course.

Spelling and standard language

This is already covered by the definition of the description field, cited above. I don’t want to point out individual examples, but there are many which demonstrate non-standard features which are fine in other, more colloquial contexts but make Typst Universe look less professional than it could be. Capitalisation is an issue, and I also spotted some typos and other non-standard features. IMHO dealing with this should be done tactfully, since power structures are involved and we want to cultivate a diverse and welcoming community, but when done well this can improve Typst Universe without doing any harm.

Conclusion

Typst itself is meticulous, and its evident much thought has been given to making it elegant, consistent, cohesive and coherent. In contrast, Typst Universe — being a repository of user-generated content — is a mixed bag. I hope what I propose here will be accepted, at least in part, and consequentially benefit the common ‘marketplace’ of our growing community 🙂

[MDLC01]

I agree with your goal, and most of the suggestions you made. My main concern is how to enforce those rules without it being annoying for the team and the package authors. We should probably look at how this is done in other projects. For example, Rust documentation tends to be pretty consistent in terms of phrasing; if they can manage to do it with so many contributors, surely this is achievable here as well.

[rwmpelstilzchen]

The decision is of the maintainers, of course, but the way I see it we shouldn’t enforce these as rules but suggest them as guidelines. Maybe it’s my own political views here, but I think it’s better if (within reason) we let people accept the guidelines voluntarily: if they chose to help Typst by contributing a package or a template, it’s not unreasonable to think they will go this extra step of following the guidelines.

I’m all for learning from other people, but if by ‘Rust documentation’ you mean the documentation of the language itself, I think we deal here with two different beasts:

• Typst Universe in its core is a repository of user-generated content, which is bound by its very nature to have some degree of inconsistency. My PR aims at reducing the inconsistency, not eliminating it, which is impossible to do without severe enforcement which will cause much more harm than good.
• The documentation of the Rust language is much more defined and bound — cohesive — in terms of what the entity in question is. It’s a limited group of closely connected complex documents that live under doc.rust-lang.org.

The difference can be likened to astronomy: the Rust documentation is like a solar system, where gravity is relatively strong and everything is bound together; our Typst Universe is — well — like a universe, which is much more loose and is made of independent entities (galaxies) which don’t interact with each other much. The analogy isn’t perfect (not on the scientific side nor the software development side… 😉) but I hope it helps to get the point across.

Alternatively, I didn’t understand you well and you mean the packages in crates.io, the Rust package registry, which is indeed much closer to Typst Universe in nature.

[MDLC01]

I meant documentation for the language itself. However, you are right that crates.io is closer to Typst Universe. And there seem to be inconsistencies on crates descriptions on crates.io just like for packages descriptions on Typst Universe, so I don't think this is a good reference.

Anyway, I agree with you about the fact that we should have clear guidelines rather than enforcing rules 👍

[rwmpelstilzchen]

Not to criticise this package in particular, but I had a look at the ‘New & Hot’ section of Typst Universe where I encountered this package, which has a URL (!) in the description:

Customizable not official template for a thesis at the JKU, derived from a template created by Fabian Scherer <https://www.linkedin.com/in/fabian-scherer-de/> with Leon Weber in an advisory role.

All of the information after the word ‘derived’ belongs in the readme. I think this demonstrates why guidelines are helpful.

[bact]

Love the guidelines, thank you for writing up.

[laurmaedje]

This PR slipped under my radar, but I like the guidelines put forth here. I'll bring this up in our next team meeting.

[laurmaedje]

Regarding full stop: The one with full stop is from me and the one without is from @reknih. :) I prefer to put a full stop in many places because otherwise it gets odd as soon as I need a second sentence. In this case, one could argue that it should not be more than one sentence. But that is why I nitpick all PRs on typst/typst to terminate source comments with a full stop.

[rwmpelstilzchen]

Great! 🎉

[elegaanz]

We discussed the guidelines, and generally agree, we just have a few comments. Can you also fix the indentation to use spaces instead of tabs, as in the rest of the README?

[elegaanz]

Can you rephrase this so that the expected length is more explicit?

Suggested change

	thoughtfully. No more than 100 characters, preferably much less.
	Ideally, it should be 40 to 60 characters long.

[elegaanz]

Could please you remove this guideline?

[laurmaedje]

For context: We think for this to be truly useful, the README would also need to be localized, and we'd also want a more machine-readable format (like a per-language table). But that's more complexity than we want to deal with for now, so we feel like it's best to leave it out for now.

[elegaanz]

Can you change these quotes to use "standard" double quotes (") for more consistency with the rest of the README please?

[elegaanz]

Can you swap this point and the previous one, so that the two "Avoid…" points are next to each other?

[elegaanz]

It would be nice to rephrase this sentence to be explicit about what "the indefinite article" is, contributors are not necessarily familiar with English grammar.