2025 Survey Draft Updates #2
Conversation
There was a problem hiding this comment.
This looks good to me, so I will approve this, but we'll need @AA-Turner or someone else with commit rights to merge.
surveys/sphinx-survey-2025.yml
Outdated
| - 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" | ||
|
|
There was a problem hiding this comment.
IIRC, from Quansight-Labs/typeform-yaml-survey#4, this was to be kept.
For now, let's add this again, and we can sanitise these questions later on.
surveys/sphinx-survey-2025.yml
Outdated
| - "Hugo" | ||
| - "Astro" | ||
| - "Pelican" | ||
| - "Nikola" | ||
| - "Eleventy" |
There was a problem hiding this comment.
To be picky, can we sort these lists alphabetically?
@Carreau is it possible to enable choice order randomisation in the typeform survey?
surveys/sphinx-survey-2025.yml
Outdated
| - "GitHub Pages" | ||
| - "Netlify" | ||
| - "Read The Docs" | ||
| - "Vercel" | ||
| - "Cloudflare Pages" | ||
| - "DigitalOcean" | ||
| - "Hetzner" | ||
| - "Render" | ||
| - "Vultr" | ||
| - "My institution has its own deployment" | ||
| - "I don't know" |
There was a problem hiding this comment.
What's the goal of the deployment question? I might suggest adding "as part of an existing website" (i.e. just uploading to a /docs directory).
Could we also tweak "my institution has its" to "we have our"? For personal projects, there's no institution, and e.g. if I was answering this with my Python committer hat on, I'm not sure I'd call docs.python.org and/or the infra team "my institution".
There was a problem hiding this comment.
My understanding is that deployment question is part of building a sense of how all the infrastructural pieces of documentation writing fit together. Knowing more about how these pieces are put together might be useful in noticing potential pain points in the places where Sphinx gets hooked into other software.
I do think it's more tangential to Sphinx than some of the others, so I could see an argument to remove it.
I'm glad you asked, because it seems important to ensure what sort of field of view seems fitting for this survey.
| - "My institution has its own deployment" | ||
| - "I don't know" | ||
|
|
||
| - title: "What markup language are you using in your documentation?" |
There was a problem hiding this comment.
Could we add ASCIIdoc(ter), XML/DITA (if this is a language!), TeX, Confluence/Jira, and perhaps split out flavours of markdown (e.g. MyST vs GFM vs CommonMark)?
surveys/sphinx-survey-2025.yml
Outdated
| @@ -215,20 +217,6 @@ questions: | |||
| - "PDF" | |||
| - "EPUB" | |||
There was a problem hiding this comment.
Can we add manpages / manual pages? Perhaps also JSON serialisation, XML, Texinfo, and plain text?
| - 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" |
There was a problem hiding this comment.
For personal use, some of this information would be interesting, though we probably have better contact with extension developers than 'ordinary' users. It might be worth thinking about a conditional section behind "do you develop a sphinx extension"? This is somewhat marginal though, so if a less complex survey is wanted then I'm content with this.
There was a problem hiding this comment.
I know there was discussion about why this was here and if it fit with the larger goals, so I thought it might be easiest to remove right now. I do know @Carreau has mentioned having more certainty that things will work right with less complex survey logic, so that is my goal right now too.
There was a problem hiding this comment.
Another of my fear is better is the enemy of good;
I thing one of our goal should be to run survey regularly, learn from results and iterate, and the more we try to be perfect the more we burnout people wanting to:
- work on the survey
- take the survey
- analyze the survey
I also think that if there are a subset of users (say extension developers), we can at the end have a "are you an extension developers, we want to know more, here is another survey"
That way we still have not taken them too much time and "Trap" them in a longer survey.
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
|
Thank you both for the review! I think I've addressed all the comments so far, notably re-adding a question, adding options to a number of questions, and alphabetizing them. I think this is ready for review again (or another next step). |
| - "AsciiDoc" | ||
| - "Confluence/Jira" | ||
| - "Markdown - CommonMark" | ||
| - "Markdown - GitHub Flavored Markdown" |
There was a problem hiding this comment.
We are repeating markdown here.
For consistency this should be changed to Markdown - GitHub
I'm proposing updates to the 2025 survey draft based on feedback in sphinx-doc discussions #13331.
I've integrated a majority of the changes (though I imagine there may be feedback on the best way to do that) except for
Drafts of these questions or how they may be integrated into existing questions are not in this PR. This is something I'm still considering the best approach for, but I didn't want to keep holding up the other changes longer.
As always, feedback is very much welcome and I will do my best to answer any questions. Thank you for making this repository and being open to the survey!