Skip to content

Add guidelines for the description field #1036

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add guidelines for the description field #1036

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 26 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ version = "0.1.0"
entrypoint = "lib.typ"
authors = ["The Typst Project Developers"]
license = "MIT"
description = "An example package."
description = "Calculate elementary arithemtics with functions"
```

Required by the compiler:
Expand Down Expand Up @@ -79,7 +79,7 @@ version = "0.1.0"
entrypoint = "lib.typ"
authors = ["Typst GmbH <https://typst.app>"]
license = "MIT-0"
description = "An IEEE-style paper template to publish at conferences and journals for Electrical Engineering, Computer Science, and Computer Engineering"
description = "IEEE-style paper to publish at conferences and journals"

[template]
path = "template"
Expand Down Expand Up @@ -173,6 +173,30 @@ are detailed below:
If you are an author of an original template not affiliated with any
organization, only the standard package naming guidelines apply to you.

- **Description:** Write simple, easily-understandable and succinct
descriptions.
- Keep it short. Try to maximise the content:length ratio and weigh your words
thoughtfully. No more than 100 characters, preferably much less.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- Avoid the word ‘Typst’, which is redundant unless your package or template
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

actually has to do with Typst itself or its ecosystem (like in the case of
[Mantys](https://typst.app/universe/package/mantys/) or
[t4t](https://typst.app/universe/package/t4t)).
- Don’t terminate your description with a full stop.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

- Avoid the words ‘package’ for packages and ‘template’ for templates;
instead:
- Packages allow the user to *do* things; use the imperative mood. For
example, `Draw Venn diagrams` is better than `A package for drawing Venn
diagrams`.
- Templates allow the user to write certain *types* of documents; clearly
indicate the type of document your template allows. For example, `Master’s
thesis at the Unseen University` is better than `A template for writing a
master’s thesis at the Unseen University`. Omit the indefinite article at
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

the beginning of the description for conciseness.
- Bilingual descriptions are welcome. If you wish to describe your package in a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could please you remove this guideline?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

language other then English, format the description like so: `ENGLISH |
ADDITIONAL-LANGUAGE` (with a vertical line as a boundary marker). Character
limit is doubled.

- **Functionality:** Packages should conceivably be useful to other users and
should expose their capabilities in a reasonable fashion.

Expand Down
Loading