2025 survey: further review of questions #6
Conversation
| type: number | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Which Python ecosystem do you feel most aligned with?" |
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.
That is to say I would like to keep this question, perhaps finding a 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
|
All these changes look good to me! Thank you for opening a PR to update it and putting references for why the choices were made, it made it very easy to follow. I'm also happy to see some questions removed. |
| # Motivation: Reflect on priorities for documentation in general. | ||
| - title: "Why did you choose the engine you use for your documentation?" | ||
| # Motivation: Reflect on priorities for documentation in general. | ||
| - title: "Why did you choose the tool/engine you use for your documentation?" |
There was a problem hiding this comment.
Is "tool" only is sufficient?
There was a problem hiding this comment.
Now that I see this question, I think the "What documentation tools/engines do you use?" question needs to be refactored.
It seems like the valuable info would be determining whether respondents primarily use Sphinx or something else, and why
In the "What documentation tools/engines do you use?" it doesn't make sense to list Sphinx and Rustdoc (for example) because we use them both and we use them for different reasons
So I think the question as it currently stands is going to generate a lot of misleading noise
There was a problem hiding this comment.
Well, OK, now I see that there are questions below that are focused on Sphinx.
I'll leave my previous comment as-is: I suggest rethinking this question and the "What documentation tools/engines do you use?" one
There was a problem hiding this comment.
I've changed my mind on this question. I think it's fine to use a single question in order to capture clusters of tools that are commonly used together, as Tania explained
| title: "Sphinx Documentation Survey (2025)" | ||
| questions: | ||
| - title: "Sphinx Usage Survey 2025" | ||
| - title: "Sphinx Documentation Survey (2025)" |
There was a problem hiding this comment.
My first reaction is that this new title immediately suggests that this is about Sphinx's documentation.
I would prefer something like "Sphinx User Survey" or "Sphinx Community Survey"
There was a problem hiding this comment.
Good points. I rephrased away from 'Sphinx User' with the intent of making it less off-putting for those that aren't using Sphinx.
Perhaps just revert to 'Sphinx Usage Survey', but make it the full survey title?
There was a problem hiding this comment.
That could work. Pinging @isabela-pf in case she has better suggestions re wording
There was a problem hiding this comment.
I think "Sphinx Community Survey" or "Sphinx Usage Survey" are the clearest without leading too much in any direction, but I am open to either.
There was a problem hiding this comment.
It could be helpful to have documentation in the title to disambiguate from Sphinx the search thing and any other uses of that name
There was a problem hiding this comment.
State of X is also a pretty common name for these types of surveys i.e. State of Sphinx
| type: number | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Which Python ecosystem do you feel most aligned with?" |
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.
That is to say I would like to keep this question, perhaps finding a better wording
Co-authored-by: Tania Allard <taniar.allard@gmail.com>
Co-authored-by: Tania Allard <taniar.allard@gmail.com>
Co-authored-by: Tania Allard <taniar.allard@gmail.com>
There was a problem hiding this comment.
Hello, I am docs lead for https://pigweed.dev and about 10 years ago I adopted Sphinx in the IoT startup I worked at
@AA-Turner asked me to leave feedback from the perspective of a technical writer using Sphinx in a corporate setting (Pigweed is a Google project)
| - "None of the above" | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Which of the following roles is closest to your job?" | ||
| - title: "Which of the following best describes your occupation?" | ||
| other: true | ||
| choices: | ||
| - "Academic researcher" | ||
| - "Data scientist" | ||
| - "Developer / Programmer" |
There was a problem hiding this comment.
| - "Developer / Programmer" | |
| - "Software Developer / Programmer / Engineer" |
Software engineer should be listed somewhere explicitly
On https://pigweed.dev I am the only technical writer and the 25-50 other people that contribute to the docs all have the literal job title of software engineer
There was a problem hiding this comment.
(Closing the loop) I don't think my original comment is too important. This is a pretty straightforward question and there is low risk of ambiguity causing noisy responses
There was a problem hiding this comment.
I have no strong feelings here so leaving it to y'all
| - "ML engineer / MLOps" | ||
| - "Product manager" | ||
| - "QA engineer" | ||
| - "Student (in full-time education)" | ||
| - "Technical support" | ||
| - "Technical writer" | ||
| - "Prefer not to answer" |
There was a problem hiding this comment.
Maybe also add hardware engineer as an option
Pretty sure that Nvidia uses Sphinx heavily. Not sure how much of their hardware teams interact with it, though…
There was a problem hiding this comment.
I don't think we need an exhaustive list here. Anything beyond what we have can be added/self-described via the "other" option
There was a problem hiding this comment.
Makes sense. Don't have a strong opinion. When my title isn't listed in a form like this, it's very obvious that I should just add it via the other open-ended text field
| - "Technical support" | ||
| - "Technical writer" | ||
| - "Prefer not to answer" | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Do you most often work on a team or independently?" | ||
| - title: "Do you most often work in a team or independently?" |
There was a problem hiding this comment.
To me it's unclear whether you want to know whether my Sphinx usage specifically is on a team or independent, or whether all of my work in general is on a team vs. independent
There was a problem hiding this comment.
This is work in general (otherwise this would be noted in the Sphinx-specific questions section)
There was a problem hiding this comment.
OK, re-reviewed the survey flow. When completing the survey it'll probably be obvious at this point that I should answer generally
There was a problem hiding this comment.
Yep, that flow/branching gets lost in the yaml format.
FYI we have a draft rendered survey at https://o4y6l78u5md.typeform.com/to/qopPUaaG
it has some bits needing fixing still but hopefully that helps with the flow
| type: number | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Which Python ecosystem do you feel most aligned with?" |
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
| @@ -119,25 +108,43 @@ questions: | |||
| - "Testing engineer" | |||
There was a problem hiding this comment.
Maybe also add Technical editor
We have official technical editors at Google and they have a very different perspective on docs projects than technical writers, and interact with docs projects in very different ways than technical writers
There was a problem hiding this comment.
I tried and list a set of "common" titles here, vs a rather exhaustive one as these vary across company and area so folks can self describe via the "other" option
| # Motivation: Reflect on priorities for documentation in general. | ||
| - title: "Why did you choose the engine you use for your documentation?" | ||
| # Motivation: Reflect on priorities for documentation in general. | ||
| - title: "Why did you choose the tool/engine you use for your documentation?" |
There was a problem hiding this comment.
Now that I see this question, I think the "What documentation tools/engines do you use?" question needs to be refactored.
It seems like the valuable info would be determining whether respondents primarily use Sphinx or something else, and why
In the "What documentation tools/engines do you use?" it doesn't make sense to list Sphinx and Rustdoc (for example) because we use them both and we use them for different reasons
So I think the question as it currently stands is going to generate a lot of misleading noise
| # Motivation: Reflect on priorities for documentation in general. | ||
| - title: "Why did you choose the engine you use for your documentation?" | ||
| # Motivation: Reflect on priorities for documentation in general. | ||
| - title: "Why did you choose the tool/engine you use for your documentation?" |
There was a problem hiding this comment.
Well, OK, now I see that there are questions below that are focused on Sphinx.
I'll leave my previous comment as-is: I suggest rethinking this question and the "What documentation tools/engines do you use?" one
| @@ -119,25 +108,43 @@ questions: | |||
| - "Testing engineer" | |||
|
|
|||
| # Motivation: Understand the constellation of tools for documentation this responder works with. | |||
| - title: "What documentation engines do you use?" | |||
| - title: "What documentation tools/engines do you use?" | |||
There was a problem hiding this comment.
The current phrasing of this question suggests that I should only list tools that I currently use.
Would it be more useful to ask:
List all documentation tools that you have ever used
I currently only use Sphinx but I have previous experience with Eleventy and lots of others
There was a problem hiding this comment.
Not really, we want to understand what people are using, their challenges/needs now.
Asking about every tool they have ever used seems unnecessary.
There was a problem hiding this comment.
OK, makes sense. Since this will probably be a yearly thing it will be cool to see changes in current tool usage over time
There was a problem hiding this comment.
I would just explicitly add currently to the question to remove the ambiguity
What documentation tools/engines do you currently use?
| 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" | ||
| - "Being able to cross-reference other pages/sections across one or multiple sites ('intersphinx')" | ||
| - "Being able to cross-reference other pages/sections across one or multiple | ||
| sites ('intersphinx')" | ||
| - "Add functionality through extensions" |
There was a problem hiding this comment.
For me it's because of the rich ecosystem of themes and extensions. Usually anything I need has already been built by someone else. Add functionality through extensions isn't broad enough IMO
There was a problem hiding this comment.
I think if you rephrase it to:
The theme and extension APIs and ecosystem
Then it becomes sufficiently broad. This covers both people who care about building their own themes / extensions and people use 3P themes / extensions from PyPI heavily
| 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: sphinx_years | ||
| 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" |
There was a problem hiding this comment.
The fact that it's open source is also an important consideration in corporate settings. pigweed.dev explicitly opted for an OSS solution even though closed source solutions also exist within Google
| - "None of the above" | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Which of the following roles is closest to your job?" | ||
| - title: "Which of the following best describes your occupation?" | ||
| other: true | ||
| choices: | ||
| - "Academic researcher" | ||
| - "Data scientist" | ||
| - "Developer / Programmer" |
There was a problem hiding this comment.
I have no strong feelings here so leaving it to y'all
| - "Technical support" | ||
| - "Technical writer" | ||
| - "Prefer not to answer" | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Do you most often work on a team or independently?" | ||
| - title: "Do you most often work in a team or independently?" |
There was a problem hiding this comment.
Yep, that flow/branching gets lost in the yaml format.
FYI we have a draft rendered survey at https://o4y6l78u5md.typeform.com/to/qopPUaaG
it has some bits needing fixing still but hopefully that helps with the flow
| type: number | ||
|
|
||
| # Motivation: Understand the responder's self-reported background and skills. | ||
| - title: "Which Python ecosystem do you feel most aligned with?" |
There was a problem hiding this comment.
This is one where I would like to hear from @isabela-pf and @AA-Turner (application + sector)
| @@ -119,25 +108,43 @@ questions: | |||
| - "Testing engineer" | |||
|
|
|||
| # Motivation: Understand the constellation of tools for documentation this responder works with. | |||
| - title: "What documentation engines do you use?" | |||
| - title: "What documentation tools/engines do you use?" | |||
There was a problem hiding this comment.
| - title: "What documentation tools/engines do you use?" | |
| - title: "What documentation tools/engines do you currently use?" |
https://github.com/orgs/sphinx-doc/discussions/13331#discussioncomment-12794511