Writing GitHub App descriptions

To list your app in the GitHub Marketplace, you'll need to provide short and long descriptions. Here's more information about how to write both descriptions.

Short descriptions on the GitHub Marketplace homepage

The community will see the "very short" description, which briefly describes the app, under your app's name on the GitHub Marketplace homepage.

GitHub App short description

Length

Write short descriptions between 40-80 characters in the required "Very short description" field when listing your app.

Content

  • Describe the app’s functionality, not a user call to action.

    USE: Lightweight project management for GitHub issues

    AVOID: Manage your projects and issues on GitHub

    Tip: You may be able to add an “s” to the end of the verb if the preferred description is a call to action.

  • Don’t repeat the app’s name in the description.

    USE: A container-native continuous integration tool

    AVOID: Skycap is a container-native CI/CD tool

Formatting

  • Always use sentence case: Only the first letter and proper nouns should be capitalized.

  • Never use punctuation. Descriptions shouldn’t include a complete sentence and definitely shouldn’t include a second sentence.

  • Only capitalize real proper nouns.

    USE: One-click delivery automation for web developers

    AVOID: One-click delivery automation for Web Developers

  • Always use the Oxford comma in lists.

  • Avoid referring to our community as “users”.

  • Avoid acronyms, unless they’re very well established (like API).

    USE: Agile task boards, estimates, and reports, without leaving GitHub

    AVOID: Agile Task Boards, Epics, Estimates and Reports, all within GitHub’s UI

Long descriptions on your GitHub App's landing page

The community will see the "introductory" and "detailed" descriptions on your GitHub App's landing page. To get to your app's landing page, click your app's name from the GitHub Marketplace homepage or category page.

GitHub App long descriptions

Length

Write a 1-2 sentence high-level summary between 150-250 characters in the required "Introductory description" field when listing your app.

To add more information, provide 3-5 value propositions with a 1-2 sentence description for each in the optional "Detailed description" field. You see this description when you click Read more from your GitHub App's landing page.

Content

  • Summaries should always begin with the app name.

  • Summaries and value propositions should be written in active voice.

Formatting

  • Always use sentence case in value proposition titles: Only the first letter and proper nouns should be capitalized.

  • Use periods. Avoid exclamations.

  • Only capitalize real proper nouns.

  • Always use the Oxford comma in lists.

  • Avoid referring to our community as “users”.

  • Avoid acronyms, unless they’re very well established (like API).