Writing your Description ​

Your product’s description is written in Markdown, allowing you to use rich text functionality to express your marketing copy. If you’re new to Markdown, visit commonmark.org for a tutorial.

How to write a description ​

Here is some advice on how you can write an effective description:

Do ​

  • Check out other products’ descriptions to learn the conventions they use.
  • Start with an elevator pitch – a few sentences that clearly explain the problem you’re solving. Make a good first impression that catches the reader’s interest.
  • After the introduction, go into further detail, but continue to keep it brief. Remember your goal is to convince the reader that your product is useful to them.
  • Consider where screenshots or videos can convey your ideas better than text. They can be added to the carousel, or placed inline using Markdown syntax (see below).

Don’t ​

  • Include a heading that repeats your product’s name – Chariz or the package manager already displays the name.
  • Include installation instructions – the user already knows they simply need to tap Install or the purchase button.
  • Use jargon (technical language) that the average user won’t understand. If you want to explain technical details, consider other avenues such as writing a blog post, or adding it to a readme or wiki in your GitHub repository (if any).
  • Repeat information already found in your product’s metadata, such as compatibility, price, support email address, social media, or tip jar.
  • Copy and paste a description from a large language model (AI). This comes off unprofessional, and often includes unnecessary details. (If you rely on AI tools because you’re not a native English speaker, let us know and we can help you to write an effective description.)

Syntax Additions ​

Your screenshots display in a widget named the carousel. This widget scrolls horizontally, and “snaps” to each item for easier navigation on touch devices. You can place the carousel wherever you feel is appropriate for your listing, however, it usually makes sense for this to be at the top.

To insert the carousel, simply place the following in your desired location:

md
:carousel:

If you do not specify a location for the carousel yourself, it will be inserted for you at the top of the description.

Screenshots ​

Description assets that are not part of the carousel can be inserted by using Markdown image syntax, directly referring to the filename of the image. This will automatically expand to the full URL of the image.

md
![Main screen of my product](awesome-screenshot.jpg)

The same syntax also works for video assets. These will play automatically, on a loop, with audio muted.

md
![Video demo of my product](awesome-demo.mp4)

Remember to provide a descriptive label of your image/video so users who use screen reader technologies such as VoiceOver can understand what your image represents. This is especially important if your image contains marketing copy, headings, or other information you believe is important for a low-vision user to be aware of just as a full-vision user would.

You may leave the description field blank by using the syntax ![](myfile.jpg) if providing a description for this image/video wouldn’t add any useful information for screen reader users. This will cause screen readers to skip over the element.

YouTube Video ​

For longer video assets, we recommend uploading the video to YouTube and embedding the YouTube player in your description. You can do so with the same image syntax as above, instead substituting in your video’s “watch” URL:

md
![Video demo of my product](https://www.youtube.com/watch?v=oHg5SJYRHA0)

Limitations ​

  • Cydia does not support playing videos inline. Videos in your description will display a play button, which the user can tap to view your video in the fullscreen player.
  • You may find that your description displays differently in Sileo. This is due to its unique Native Depiction format. We make our best attempts to ensure rendering of Native Depictions closely matches the HTML-based rendering found on the chariz.com website and other package managers such as Cydia and Zebra, but this process can be imperfect. While it’s not always possible to perfectly match the HTML-based description, if you believe there is a rendering issue with your description in Sileo, please contact us.
  • Aside from the specific functionality mentioned in the prior section, loading resources from external websites is not supported. Chariz uses a browser feature named Content Security Policy to enforce this.
  • To protect user privacy, upon clicking a link in your description, the HTTP Referer header will only contain https://chariz.com/, or in some cases, will not be present at all. This allows your analytics service to determine that the page was referred to from Chariz, without revealing the specific address the user visited from.

© HASHBANG Productions