2025 survey: further review of questions #6
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,3 @@ | ||
| # Survey Objective | ||
| # ================ | ||
| # | ||
|
|
@@ -14,77 +12,85 @@ | |
| # People who interact with documentation, especially those who contribute to | ||
| # or extend documentation. Use of Sphinx is encouraged but not required. | ||
|
|
||
| title: "State of Sphinx (2025)" | ||
| questions: | ||
| - title: "Sphinx Usage Survey (2025)" | ||
| type: statement | ||
| description: >- | ||
| We’re running this survey to understand requirements for documentation | ||
| tools in 2025, how they are used, and how well tools support their users. | ||
| This survey is being run on behalf of the [Sphinx] community, but is | ||
| open to anyone who works with or contributes to documentation, regardless | ||
| of whether you use Sphinx. | ||
|
|
||
| We will use this information to aid community discussion about improvements | ||
| to Sphinx. Results will be public, with any 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 and [Quansight Labs]; survey | ||
| data will be deleted from any private accounts once made public. If you | ||
| have any questions, contact Tania Allard (Director of Quansight Labs) | ||
| at tallard@quansight.com and mention Sphinx Survey 2025 in the subject line. | ||
|
|
||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| [Sphinx]: https://www.sphinx-doc.org/ | ||
| [Quansight Labs]: https://labs.quansight.org/ | ||
|
|
||
| # Motivation: Understand how the responder views themselves in relation to Sphinx. | ||
| - title: "What is your relation to the Sphinx project?" | ||
| multiple: true | ||
| choices: | ||
| - "I read documentation that is built with Sphinx" | ||
| - "I use Sphinx to build documentation" | ||
| - "I maintain or have contributed to a Sphinx extension" | ||
| - "I maintain or have contributed to a Sphinx theme" | ||
| - "I have contributed to the Sphinx project" | ||
| - "None of the above" | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Which of the following best describes your occupation?" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| other: true | ||
| choices: | ||
| - "Academic researcher" | ||
| - "Data scientist" | ||
| - "Manager" | ||
| - "ML engineer / MLOps" | ||
| - "Product manager" | ||
| - "QA engineer" | ||
| - "Software Developer / Programmer / Engineer" | ||
| - "Student (in full-time education)" | ||
| - "Technical support" | ||
| - "Technical writer" | ||
| - "Prefer not to answer" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Do you most often work in a team or independently?" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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" | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "How many years of professional experience do you have?" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| type: number | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
|
There was a problem hiding this comment. Cf. discussion in https://github.com/orgs/sphinx-doc/discussions/13331#discussioncomment-12794511. We could keep a general 'industry/sector' question though, if valuable. There was a problem hiding this comment. I think an "application area" (i.e. DS, Infrastructure, ML) is what we are after vs sector (that tends to be things like Healthcare, Agriculture, IT). This can help with some mapping within subcommunities. For example the PSF Python survey uses "Purposes for using Python" https://lp.jetbrains.com/python-developers-survey-2023/ but we are removing the Python specificity in this PR so might need better wording. There was a problem hiding this comment. I would do both sector and application I have a feeling that Sphinx is used way more widely (sector-wise) than we all may realize and it may be pretty eye-opening to get some numbers behind it There was a problem hiding this comment. This is one where I would like to hear from @isabela-pf and @AA-Turner (application + sector) There was a problem hiding this comment. I don't think I know enough about Sphinx to recommend how helpful this question may or may not be, but I can explain intent in case that helps clarify how to rework it with non-Python and more fitting Sphinx options. Knowing what communities people responding consider themselves part of both helps us understand the sample we end up with as well as information about where Sphinx might be used. Even if it's only for understanding what kind of sample we are working with, I would recommend something like this being part of the survey because it's not as tied to studies or jobs or more rigid external options. Application is closer to what I was thinking when writing this question, but if there's interest in industry/sectors too I'm sure there's options we can draw on there. I don't think it undermines the purpose of the survey, only adds to the length. There was a problem hiding this comment. I am less interested about external groupings at the sector or industry-level and I belive the application area is better aligned with the original intent of the survey as a whole |
||
| - title: "Which ecosystem(s) do you feel most aligned with?" | ||
| multiple: true | ||
| other: true | ||
| choices: | ||
| - "Academia" | ||
| - "Analytics / Visualisation" | ||
| - "Data Science" | ||
| - "Embedded / Hardware" | ||
| - "Enterprise" | ||
| - "Game Development" | ||
| - "Infrastructure / DevOps" | ||
| - "Machine Learning" | ||
| - "Mobile Development" | ||
| - "Multimedia / Creative" | ||
| - "Scientific Python" | ||
| - "Web" | ||
| - "Prefer not to answer" | ||
|
|
@@ -99,8 +105,8 @@ questions: | |
| other: true | ||
| choices: | ||
| - "As a part of my full-time job" | ||
| - "As a part of my part-time job, contract, or other employment" | ||
| - "As a part of a side or non-paid/voluntary project" | ||
| - "I do not use documentation tools" | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
|
|
@@ -115,29 +121,72 @@ questions: | |
| - "Developer" | ||
| - "Educator" | ||
| - "Extension developer/maintainer" | ||
| - "Technical editor" | ||
| - "Technical writer" | ||
| - "Testing engineer" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - "Theme developer/maintainer" | ||
|
|
||
| # Motivation: Understand the constellation of tools for documentation this responder works with. | ||
| - title: "What documentation authoring software do you currently use?" | ||
| multiple: true | ||
| other: true | ||
| choices: | ||
| - "Antora" | ||
| - "AsciiDoc" | ||
| - "Astro" | ||
| - "Confluence" | ||
| - "docfx" | ||
| - "docsify" | ||
| - "Doctave" | ||
| - "Docusaurus" | ||
| - "docz" | ||
| - "Eleventy" | ||
| - "GitBook" | ||
| - "Hugo" | ||
| - "Jekyll" | ||
| - "JupyterBook" | ||
| - "mdBook" | ||
| - "Mintlify" | ||
| - "MkDocs" | ||
| - "Nikola" | ||
| - "Pelican" | ||
| - "readme.com" | ||
| - "Sphinx" | ||
| - "Starlight" | ||
| - "VitePress" | ||
| - "Zola" | ||
| - "I don’t know" | ||
|
There was a problem hiding this comment. There are a lot of missing options here. I can dig up more if helpful.
There was a problem hiding this comment. Same comment as before we are not trying to be exhaustive and add all possible options. There was a problem hiding this comment. This is the only one where I have a strong opinion that it actually should be exhaustive. It's really important to understand the clusters of tools that are used together, in order for Sphinx to have a better sense of where it needs to go in the future. I worry that respondents will not remember all of the tools they use, or it will be awkward to manually list them, and therefore we will get an incomplete picture of the tooling landscape There was a problem hiding this comment. But I imagine that having only a single question with an exhaustive list may be overwhelming so it still makes sense to me to split this up into more focused questions: What authoring software do you currently use?
What API reference auto-generation tools do you use?
What other documentation tools do you use?
There was a problem hiding this comment. I like the proposed split into authoring/API/others. I do, however, think we do need to keep those lists/choices somewhat curated still and not try and add every tool existing. There was a problem hiding this comment. Here's my take at a curated list for each. Authoring software:
(The assumption is that Sphinx's main competitors are docs-focused SSGs.) API tools:
The only "other tools" I can think of are Vale and Pandoc so maybe we drop the "other tools" question There was a problem hiding this comment. I think that could work. Agree that if we are looking for an exhaustive list this is probably the best way to break that up. Thank you for elaborating! Would it be helpful for me to format this as a suggestion on the PR, or are you waiting for feedback right now? |
||
|
|
||
| - title: "What API reference auto-generation tools do you use?" | ||
| multiple: true | ||
| other: true | ||
| choices: | ||
| - "autodoc (Sphinx)" | ||
| - "Doxygen" | ||
| - "GoDoc" | ||
| - "JavaDoc" | ||
| - "JSDoc" | ||
| - "OpenAPI" | ||
| - "rustdoc" | ||
| - "TypeDoc" | ||
| - "None" | ||
|
|
||
| # Motivation: Explore patterns in output priorities. This might be useful for contextualising other answers. | ||
| - title: "In which formats do you publish your documentation?" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| multiple: true | ||
| other: true | ||
| choices: | ||
| - "EPUB" | ||
| - "HTML" | ||
| - "JSON serialisation" | ||
| - "manual pages (manpages)" | ||
| - "PDF / LaTeX" | ||
| - "Plain text" | ||
| - "Texinfo" | ||
| - "XML" | ||
|
|
||
| # Motivation: Understand the constellation of tools for documentation this responder works with. | ||
| - title: "Where do you deploy your documentation webpages?" | ||
| multiple: true | ||
| other: true | ||
| choices: | ||
|
|
@@ -150,9 +199,10 @@ questions: | |
| - "Render" | ||
| - "Vercel" | ||
| - "Vultr" | ||
| - "As a part of an existing website" | ||
| - "We don’t publish HTML webpages" | ||
| - "We have our own deployment" | ||
| - "I don’t know" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| # Motivation: Understand the constellation of tools for documentation this responder works with. | ||
| - title: "What markup language are you using in your documentation?" | ||
|
|
@@ -171,16 +221,38 @@ questions: | |
|
|
||
| # Motivation: Understand the constellation of tools for documentation this responder works with. | ||
| - title: "Which Python docstring style do you use?" | ||
| description: >- | ||
| Select N/A if you don’t use Python or Python docstrings. | ||
|
|
||
| Google-style docstrings look like: | ||
| ```rst | ||
| Arguments: | ||
| my_param (type): description | ||
| ``` | ||
|
|
||
| Numpydoc-style docstrings look like: | ||
| ```rst | ||
| Arguments | ||
| --------- | ||
| my_param : type | ||
| description | ||
| ``` | ||
|
|
||
| Sphinx-style docstrings look like: | ||
| ```rst | ||
| :param [my_param]: description | ||
| ``` | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| multiple: true | ||
| other: true | ||
| choices: | ||
| - "Google format" | ||
| - "Numpydoc format" | ||
| - "Sphinx format" | ||
| - "Markdown" | ||
| - "I don’t know" | ||
| - "I do not write docstrings" | ||
|
|
||
| # Motivation: Reflect on priorities for documentation in general. | ||
| - title: >- | ||
| Which of the following is most important to you in a documentation site? | ||
| multiple: true | ||
|
|
@@ -192,8 +264,8 @@ questions: | |
| - "Stability" | ||
| - "Variety of features" | ||
|
|
||
| # Motivation: Reflect on priorities for documentation in general. | ||
| - title: "Why did you choose the tool you use for your documentation?" | ||
| multiple: true | ||
| other: true | ||
| choices: | ||
|
|
@@ -202,53 +274,60 @@ questions: | |
| - "Performance" | ||
| - "Stability" | ||
| - "Variety of features" | ||
| - "Its ecosystem of plugins" | ||
| - "Other projects in my ecosystem were using it" | ||
| - "It was chosen by others or before I joined" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| # BRANCH POINT | ||
| - 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: "no_sphinx" | ||
| otherwise_jump_to: "yes_sphinx" | ||
|
|
||
| # Motivation: Gather information on possible motivations for documentation tool selection. | ||
| - title: >- | ||
| If you don’t use Sphinx for your documentation, | ||
| please explain why you chose the one you are using | ||
| ref: "no_sphinx" | ||
| type: long_text | ||
| always_jump_to: the_end | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "How many years have you been using Sphinx?" | ||
| ref: "yes_sphinx" | ||
| type: number | ||
|
|
||
| # Motivation: Explore patterns in what people using Sphinx value in it. | ||
| - title: "What is the main reason you use Sphinx?" | ||
| other: true | ||
| choices: | ||
| - "API documentation generation from Python docstrings" | ||
AA-Turner marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - "Being able to cross-reference other pages/sections across one or multiple | ||
| sites ('intersphinx')" | ||
| - "The theme and extension APIs and ecosystem" | ||
| - "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" | ||
| - "It's open source / permissively licenced" | ||
| - "Sphinx’s ease of use" | ||
| - "Sphinx’s performance" | ||
| - "Sphinx’s stability" | ||
| - "Sphinx’s release schedule" | ||
|
|
||
| # Motivation: Understand the constellation of tools for documentation this responder is around. | ||
| - title: "Does your project use custom Sphinx extensions?" | ||
| description: >- | ||
| A custom Sphinx extension is one that is developed by the project itself, | ||
| or an organisation-developed extension that is intended mainly for internal | ||
| use. If you are unsure or don’t know, select 'I don’t know'. | ||
| choices: | ||
| - "My project is a custom Sphinx extension(s)" | ||
| - "No, my project does not use custom Sphinx extensions" | ||
| - "Yes, my project uses custom Sphinx extensions" | ||
| - "I don’t know" | ||
|
|
||
| # Motivation: Understand the constellation of tools for documentation this responder works with. | ||
|
|
@@ -270,27 +349,13 @@ questions: | |
| - "Sphinx Immaterial" | ||
| - "I don’t know" | ||
|
|
||
| # Motivation: Explore patterns in what people using Sphinx struggle with. | ||
| - title: >- | ||
| Please rank the issues you face when working with Sphinx | ||
| from 1 (most important, I wish this was fixed yesterday) | ||
| to 7 (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: | ||
|
|
@@ -314,7 +379,7 @@ questions: | |
| ref: the_end | ||
| type: statement | ||
| description: >- | ||
| Survey data will be publicly available once anonymised. For updates, | ||
| follow https://github.com/orgs/sphinx-doc/discussions/13331. If you | ||
| have any questions, contact Tania Allard (Director of Quansight Labs) | ||
| at tallard@quansight.com and mention Sphinx Survey 2025 in the subject line. | ||
Uh oh!
There was an error while loading. Please reload this page.