survey.yaml

id: 'Oq55zKog'
title: 'Sphinx Survey Jan 30'
questions:
  - title: 'Sphinx Usage Survey 2025'
    type: statement
    description: |
      Sphinx Documentation User Survey 2025

      Help the Sphinx community understand who is using Sphinx, how they are using it, and how well it supports the people using it. We will use this information to aid community discussion about improvements to Sphinx.

      Results will be public with identifying information removed. Open text field questions may be quoted, but will not be shown in full.

      This survey is run by the Sphinx community; survey data will be deleted from any private accounts once made public. If you have any questions, reach out to [Contact to be determined].

  - title: 'Tell us about you'
    description: "First, we'd like to know about how you work and what tools you use."
    type: statement

  - title: 'Which of the following roles is closest to your job?'
    other: true
    choices:
      - 'Academic researcher'
      - 'Data scientist'
      - 'Developer / Programmer'
      - 'ML engineer / MLOps'
      - 'Product manager'
      - 'QA engineer'
      - 'Technical support'
      - 'Technical writer'
      - 'Prefer not to answer'

  - title: 'Do you most often work on a team or independently?'
    other: true
    choices:
      - 'I most often work on projects independently'
      - 'I most often work on projects as part of a team'
      - 'I spend about equal time working on projects independently as I do on a team'
      - 'Prefer not to answer'

  - title: 'How many years have you been using Python for?'
    type: number

  - title: 'Which Python ecosystem do you feel most aligned with?'
    multiple: true
    other: true
    choices:
      - 'Data Science'
      - 'Machine Learning'
      - 'Web'
      - 'Scientific Python'
      - 'Infrastructure'
      - 'Prefer not to answer'

  - title: 'For how many years have you been using documentation tools?'
    type: number

  - title: 'In which of the following contexts do you use documentation tools?'
    multiple: true
    other: true
    choices:
      - 'As a part of my full-time job'
      - 'As a part of my part-time, contract, or other employment'
      - 'As a part of a side or non-paid project'
      - 'I do not use documentation tools'

  - title: 'How would you identify your role in your documentation-related projects?'
    multiple: true
    other: true
    choices:
      - 'Designer'
      - 'Developer'
      - 'Data scientist'
      - 'Educator'
      - 'Technical writer'
      - 'Community manager'
      - 'Testing engineer'
      - 'Extension developer/maintainer'

  - title: 'What documentation engines do you use?'
    multiple: true
    other: true
    choices:
      - 'MyST'
      - 'Docusaurus'
      - 'Mkdocs'
      - 'JupyterBook'
      - 'Sphinx'
      - 'None'
      - 'I don’t know'

  - title: 'Where do you deploy your documentation pages?'
    multiple: true
    other: true
    choices:
      - 'GitHub Pages'
      - 'Netlify'
      - 'Read The Docs'
      - 'My institution has its own deployment'

  - title: 'What markup language are you using in your documentation?'
    multiple: true
    other: true
    choices:
      - 'Markdown'
      - 'RST'
      - 'I don’t know'

  - title: 'What markup language are you using in your docstrings?'
    multiple: true
    other: true
    choices:
      - 'Markdown'
      - 'RST'
      - 'Numpydoc format'
      - 'Google format'
      - 'I don’t know'


  - title: 'Which of the following is most important to you in a documentation site?'
    multiple: true
    other: true
    choices:
      - 'Ease of use'
      - 'Performance'
      - 'Stability'
      - 'Frequent updates'
      - 'Variety of features'

  - title: 'Why did you choose the engine you use for your documentation?'
    multiple: true
    other: true
    choices:
      - 'Ease of use'
      - 'Performance'
      - 'Stability'
      - 'Frequent updates'
      - 'Variety of features'
      - 'Other projects in my ecosystem were using it'
      - 'It was chosen by others on the project'

  - title: 'Do you use Sphinx? (Whether working on the project, using it for another project, or developing Sphinx-extensions)'
    type: 'yes_no_jump'
    ref: 'use_sphinx'
    if_no_jump_to: arent_sphinx
    otherwise_jump_to: sphinx_years

  - title: 'If you aren’t using Sphinx for your documentation, please explain why you chose the one you are using'
    ref: 'arent_sphinx'
    type: long_text
    always_jump_to: the_end


  - title: 'How many years have you been using Sphinx?'
    ref: sphinx_years
    type: number

  - title: 'What is the main reason you use Sphinx?'
    other: true
    choices:
      - 'Python API documentation generation (docstrings)'
      - 'Narrative documentation'
      - 'Educational materials'
      - 'Other projects in my ecosystem were using Sphinx'
      - 'Someone on my team knew how to use Sphinx'
      - 'I joined a project that was already using Sphinx'
      - 'Sphinx’s ease of use'
      - 'Sphinx’s performance'
      - 'Sphinx’s stability'
      - 'Sphinx’s release schedule'

  - title: 'Does your project use custom Sphinx extensions?'
    choices:
      - 'My project is a custom Sphinx extension(s)'
      - 'No, my project does not use custom Sphinx extensions'
      - 'Yes, my project does use custom Sphinx extensions'
      - 'I don’t know'

  - title: 'What theme(s) do you use? Select all that apply.'
    multiple: true
    other: true
    choices:
    - 'Whatever comes with Sphinx by default'
    - 'Alabaster'
    - 'Read The Docs'
    - 'Pydata Sphinx Theme'
    - 'Material design'
    - 'Something else/I don’t know'

  - title: 'In which formats do you publish your documentation with sphinx?'
    multiple: true
    other: true
    choices:
      - 'HTML'
      - 'PDF'
      - 'EPUB'

  - title: 'How comfortable do you feel when working with docutils?'
    choices:
      - 'Very comfortable'
      - 'Comfortable'
      - 'Neutral'
      - 'Uncomfortable'
      - 'Very uncomfortable'
      - "I don't know or don't work with docutils"

  - title: 'What is the biggest challenge you face when searching for documentation on Sphinx internals?'
    type: long_text

  - title: 'Please rank the issues you face when working with Sphinx from 1 (most important, I wish this was fixed yesterday) to 5 (least important, this can wait).'
    description: "That is to say, the issues you'd like to be fixed first, and where should resources be allocated."
    type: ranking
    choices:
      - 'RST syntax is too complicated'
      - 'Sphinx is missing features I want'
      - 'Performance issues'
      - 'Sphinx breaks too often'
      - 'No native support for Markdown'

  - title: 'Are there any other issues you face when working with Sphinx?'
    type: long_text

  - title: 'If there are any features you wish Sphinx had, what would they be?'
    type: long_text

  - title: 'Thanks for your participation'
    ref: the_end
    type: statement
    description: |
        Add contact detail again, and maybe link to an open issue people can subscribe on github for when the results will be available. Likely on the typeform repository.