2025 survey: further review of questions #6

AA-Turner · 2025-04-10T17:18:00Z

https://github.com/orgs/sphinx-doc/discussions/13331#discussioncomment-12794511

surveys/sphinx-survey-2025.yml

AA-Turner · 2025-04-10T17:24:33Z

surveys/sphinx-survey-2025.yml

  type: number

-# Motivation: Understand the responder's self-reported background and skills.
- title: "Which Python ecosystem do you feel most aligned with?"


Cf. discussion in https://github.com/orgs/sphinx-doc/discussions/13331#discussioncomment-12794511. We could keep a general 'industry/sector' question though, if valuable.

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

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

This is one where I would like to hear from @isabela-pf and @AA-Turner (application + sector)

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.

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

surveys/sphinx-survey-2025.yml

isabela-pf · 2025-04-10T18:55:36Z

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.

timhoffm · 2025-04-10T21:41:58Z

surveys/sphinx-survey-2025.yml

-# 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?"


Is "tool" only is sufficient?

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

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

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

surveys/sphinx-survey-2025.yml

trallard · 2025-04-11T12:13:27Z

surveys/sphinx-survey-2025.yml

+title: "Sphinx Documentation Survey (2025)"
 questions:
- title: "Sphinx Usage Survey 2025"
+- title: "Sphinx Documentation Survey (2025)"


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"

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?

That could work. Pinging @isabela-pf in case she has better suggestions re wording

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.

It could be helpful to have documentation in the title to disambiguate from Sphinx the search thing and any other uses of that name

State of X is also a pretty common name for these types of surveys i.e. State of Sphinx

State of Rust

State of CSS

State of JS

surveys/sphinx-survey-2025.yml

trallard · 2025-04-11T12:27:59Z

surveys/sphinx-survey-2025.yml

  type: number

-# Motivation: Understand the responder's self-reported background and skills.
- title: "Which Python ecosystem do you feel most aligned with?"


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

surveys/sphinx-survey-2025.yml

Co-authored-by: Tania Allard <taniar.allard@gmail.com>

kaycebasques

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)

surveys/sphinx-survey-2025.yml

kaycebasques · 2025-04-14T21:44:59Z

surveys/sphinx-survey-2025.yml

  type: number

-# Motivation: Understand the responder's self-reported background and skills.
- title: "Which Python ecosystem do you feel most aligned with?"


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

surveys/sphinx-survey-2025.yml

kaycebasques · 2025-04-14T22:01:02Z

surveys/sphinx-survey-2025.yml

-# 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?"


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

kaycebasques · 2025-04-14T22:03:29Z

surveys/sphinx-survey-2025.yml

-# 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?"


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

surveys/sphinx-survey-2025.yml

trallard · 2025-04-16T15:22:41Z

surveys/sphinx-survey-2025.yml

  type: number

-# Motivation: Understand the responder's self-reported background and skills.
- title: "Which Python ecosystem do you feel most aligned with?"


This is one where I would like to hear from @isabela-pf and @AA-Turner (application + sector)

surveys/sphinx-survey-2025.yml

isabela-pf · 2025-04-30T00:23:15Z

Hi all, I'm checking in if there's anything I can do to help move this PR forward. It looks like discussion has died down for now.

Personally, I think this is in a state where it can be merged. Is there anything blocking it?

kaycebasques · 2025-04-30T01:30:23Z

I don't have a blocking vote (or ability to approve the PR) but LGTM from my end 👍

Co-authored-by: Kayce Basques <kaycebasques@gmail.com>

Co-authored-by: Tania Allard <taniar.allard@gmail.com>

AA-Turner · 2025-05-01T04:25:24Z

Sorry for the delay!

2025 survey: further review of questions

1ca7b93

AA-Turner commented Apr 10, 2025

View reviewed changes

timhoffm reviewed Apr 10, 2025

View reviewed changes

surveys/sphinx-survey-2025.yml Show resolved Hide resolved

trallard reviewed Apr 11, 2025

View reviewed changes

AA-Turner and others added 3 commits April 12, 2025 05:16

Update sphinx-survey-2025.yml

c5a84dc

Co-authored-by: Tania Allard <taniar.allard@gmail.com>

Update sphinx-survey-2025.yml

044bbb8

Co-authored-by: Tania Allard <taniar.allard@gmail.com>

Update sphinx-survey-2025.yml

e14cb3c

Co-authored-by: Tania Allard <taniar.allard@gmail.com>

kaycebasques reviewed Apr 14, 2025

View reviewed changes

trallard reviewed Apr 16, 2025

View reviewed changes

AA-Turner and others added 7 commits May 1, 2025 05:09

Update copyright, title, restore 'ecosystem' question

dfe5ad3

Add 'engineer'

f5aa246

Co-authored-by: Kayce Basques <kaycebasques@gmail.com>

Update surveys/sphinx-survey-2025.yml

c04ce25

Co-authored-by: Kayce Basques <kaycebasques@gmail.com>

Update surveys/sphinx-survey-2025.yml

8d0c490

Co-authored-by: Tania Allard <taniar.allard@gmail.com>

Add more options

c5217a5

Split 'tools' question per Kayce's list

3d52428

Sort lists

4408004

AA-Turner merged commit 9866f79 into master May 1, 2025

AA-Turner deleted the aat-review branch May 1, 2025 04:25

Uh oh!

2025 survey: further review of questions #6

2025 survey: further review of questions #6

Uh oh!

Conversation

AA-Turner commented Apr 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

isabela-pf commented Apr 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AA-Turner Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kaycebasques left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AA-Turner commented Apr 10, 2025 •

edited

Loading

AA-Turner Apr 11, 2025 •

edited

Loading