2025 Survey Draft Updates (#2)

Co-authored-by: Isabela Presedo-Floyd <irpf@Isabelas-MacBook-Pro.local>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: 3 people

surveys/sphinx-survey-2025.yml

@@ -1,5 +1,11 @@
 # Copyright (c) 2025, Quansight Inc.
 
+# Objective: Gain basic insight about about Sphinx in the wild; who is using it, for what, with what, and with what priorities?
+# The goal is to augment discussions on features and issues with feedback that can be followed up on. The survey will not provide prescriptive solutions.
+
+# Target audience: People who interact with documentation, especially those who contribute to or extend documentation. Use of Sphinx is encouraged but not required.
+
+
 title: "Sphinx Survey 2025"
 questions:
   - title: "Sphinx Usage Survey 2025"
@@ -31,19 +37,20 @@ questions:
       - "I build extensions for Sphinx"
       - "I maintain a Sphinx theme"
       - "I contribute to Sphinx"
+      - "None of the above"
 
   - 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"
+  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
@@ -85,23 +92,28 @@ questions:
     multiple: true
     other: true
     choices:
+      - "Community manager"
       - "Designer"
       - "Developer"
       - "Data scientist"
       - "Educator"
+      - "Extension developer/maintainer"
       - "Technical writer"
-      - "Community manager"
       - "Testing engineer"
-      - "Extension developer/maintainer"
 
   - title: "What documentation engines do you use?"
     multiple: true
     other: true
     choices:
-      - "MyST"
+      - "Astro"
       - "Docusaurus"
-      - "Mkdocs"
+      - "Eleventy"
+      - "Hugo"
       - "JupyterBook"
+      - "Mkdocs"
+      - "MyST"
+      - "Nikola"
+      - "Pelican"
       - "Sphinx"
       - "None"
       - "I don’t know"
@@ -110,27 +122,41 @@ questions:
     multiple: true
     other: true
     choices:
+      - "Cloudflare Pages"
+      - "DigitalOcean"
       - "GitHub Pages"
+      - "Hetzner" 
       - "Netlify"
       - "Read The Docs"
-      - "My institution has its own deployment"
+      - "Render"
+      - "Vercel" 
+      - "Vultr"
+      - "We have our own deployment"
+      - "As a part of an existing website"
+      - "I don't know"
 
   - title: "What markup language are you using in your documentation?"
     multiple: true
     other: true
     choices:
-      - "Markdown"
+      - "AsciiDoc"
+      - "Confluence/Jira"
+      - "Markdown - CommonMark"
+      - "Markdown - GitHub Flavored Markdown"
+      - "Markdown - MyST"
       - "reStructuredText"
+      - "TeX"
+      - "XML/DITA"
       - "I don’t know"
 
   - title: "What markup language are you using in your docstrings?"
     multiple: true
     other: true
     choices:
+      - "Google format"
       - "Markdown"
-      - "reStructuredText"
       - "Numpydoc format"
-      - "Google format"
+      - "reStructuredText"
       - "I don’t know"
 
   - title:
@@ -139,19 +165,19 @@ questions:
     other: true
     choices:
       - "Ease of use"
+      - "Frequent updates"
       - "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"
+      - "Frequent updates"
       - "Performance"
       - "Stability"
-      - "Frequent updates"
       - "Variety of features"
       - "Other projects in my ecosystem were using it"
       - "It was chosen by others on the project"
@@ -178,16 +204,17 @@ questions:
   - title: "What is the main reason you use Sphinx?"
     other: true
     choices:
-      - "Python API documentation generation (docstrings)"
-      - "Narrative documentation"
-      - "Educational materials"
+      - "API documentation generation from Python docstrings"
+      - "Being able to cross-reference other pages/sections across one or multiple sites ('intersphinx')"
+      - "Add functionality through extensions"
       - "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:
@@ -202,32 +229,30 @@ questions:
     choices:
       - "Whatever comes with Sphinx by default"
       - "Alabaster"
-      - "Read The Docs"
-      - "Pydata Sphinx Theme"
+      - "Furo"
       - "Material design"
+      - "Pydata Sphinx Theme"
+      - "Python Docs Sphinx Theme"
+      - "Read The Docs"
+      - "Shibuya"
+      - "Sphinx Awesome Theme"
+      - "Sphinx Book Theme"
+      - "Sphinx Bootstrap Theme"
+      - "Sphinx Immaterial"
       - "Something else/I don’t know"
 
   - title: "In which formats do you publish your documentation with sphinx?"
     multiple: true
     other: true
     choices:
+      - "EPUB"
       - "HTML"
+      - "JSON serialisation"
+      - "manpages / manual pages"
       - "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
+      - "Plain text"
+      - "Texinfo"
+      - "XML"
 
   - title:
       "Please rank the issues you face when working with Sphinx from 1 (most
@@ -238,11 +263,11 @@ questions:
       should resources be allocated."
     type: ranking
     choices:
-      - "reStructuredText syntax is too complicated"
-      - "Sphinx is missing features I want"
+      - "No native support for Markdown"
       - "Performance issues"
+      - "reStructuredText syntax is too complicated"
       - "Sphinx breaks too often"
-      - "No native support for Markdown"
+      - "Sphinx is missing features I want"
 
   - title: "Are there any other issues you face when working with Sphinx?"
     type: long_text