# Reporting Issues (/docs/reporting-issues)



The best way to report a bug, ask for a feature, or flag something confusing is
to **open an issue on GitHub**. Issues are public, searchable, and let the team
track and respond to your report. You don't need to be a developer — this page
walks you through it from scratch.

## Create a GitHub account [#create-a-github-account]

If you don't already have one, you'll need a free GitHub account.

<Steps>
  <Step>
    ### Go to the sign-up page [#go-to-the-sign-up-page]

    Open [github.com/signup](https://github.com/signup) in your browser.
  </Step>

  <Step>
    ### Enter your details [#enter-your-details]

    Provide an email address, a password, and a username. GitHub will send a code
    to your email to confirm it's really you.
  </Step>

  <Step>
    ### Verify and finish [#verify-and-finish]

    Enter the code from your email. That's it — you now have a GitHub account and
    can create issues.
  </Step>
</Steps>

<Callout title="Already have an account?">
  Just [sign in](https://github.com/login) and skip to the next section.
</Callout>

## File an issue [#file-an-issue]

<Steps>
  <Step>
    ### Open the issues page [#open-the-issues-page]

    Go to the project's issue tracker:
    [github.com/unicef/adt-studio/issues](https://github.com/unicef/adt-studio/issues).
  </Step>

  <Step>
    ### Search first [#search-first]

    Type a few keywords into the search box to check whether someone has already
    reported the same thing. If you find a matching issue, add a comment or a 👍
    reaction instead of opening a duplicate — it helps the team gauge how many
    people are affected.
  </Step>

  <Step>
    ### Choose a template [#choose-a-template]

    Click the green **New issue** button. You'll be asked to pick the template that
    matches what you're reporting — choose the closest one:

    * **Bug Report** — something isn't working the way it should.
    * **Feature Request** — suggest a new feature or improvement.
    * **Accessibility Issue** — report an accessibility barrier in the app or in a
      book it produced.
    * **Documentation Issue** — something in these docs is wrong, unclear, or
      missing.
    * **Question / Support** — ask how to do something in ADT Studio.
  </Step>

  <Step>
    ### Fill in the form [#fill-in-the-form]

    Each template is a short form that asks for exactly what the team needs, so just
    follow the fields. A few tips for a report that's quick to act on:

    * **A clear title*&#x2A; — summarize it in one line (e.g. &#x2A;"Audio fails to generate
      for Portuguese"*).
    * **What happened vs. what you expected.**
    * **Steps to reproduce it** — what you clicked, in order, so the team can see it
      too.
    * **Your setup** — your operating system (Windows, macOS, or Linux) and the
      ADT Studio version.
    * **Screenshots or a screen recording** — drag image files straight into the
      text box. A picture often explains more than a paragraph.
  </Step>

  <Step>
    ### Submit [#submit]

    Click **Submit new issue**. You'll get an email whenever someone responds, and
    you can reply right from your inbox or on the issue page.
  </Step>
</Steps>

<Callout type="warn" title="Don't include sensitive information">
  Issues are public. Never paste passwords, API keys, or personal data into an
  issue — blur or remove them from screenshots first.
</Callout>