Add suggestions to survey #5
Conversation
surveys/sphinx-survey-2025.yml
Outdated
| @@ -155,7 +155,7 @@ questions: | |||
| - "I don't know" | |||
|
|
|||
| # Motivation: Understand the constellation of tools for documentation this responder works with. | |||
| - title: "What markup language are you using in your documentation?" | |||
| - title: "What markup language do you like using in your documentation?" | |||
There was a problem hiding this comment.
I think we care more about what people want rather than what they use. e.g. they may use reStructuredText because it's built in but would rather have Markdown.
These are two seperate topics and we could also ask both. But if limited to one of them, what they want feels more important.
There was a problem hiding this comment.
I suppose changing this question relates to why we're asking it. What does preferred/actual markup language tell us? Respondents may have a different preference from what they actually use, but inertia, network effects, business decisions, etc mean that they don't change.
There was a problem hiding this comment.
Exactly, and what can we do with that information? How will this guide our future development decisions?
-
I think the actually used language alone doesn't tell us much. I anticipate there are a lot of reST users because the survey is from a sphinx context and reST is the default language. - We basically could even scrape GitHub to get current language usage. - But what actions are influenced by that insight?
-
answer on what is actually used.- For the language preference, the implications are clearer. If people are satisfied with reStructuredText, we don't have specific actions. If they rather like markdown, better integration with MyST may be an option.
There was a problem hiding this comment.
These could actually be two distinct questions, but we originally opted to ask about the markup they use right now to map the current usage.
The "what markup you like" is too vague and does not necessarily mean that someone would choose/change to something they like/enjoy using/are more familiar with.
There was a problem hiding this comment.
| - title: "What markup language do you like using in your documentation?" | |
| - title: "What markup language are you using in your documentation?" |
| - "Google format (my_param (type): description)" | ||
| - "Numpydoc format (my_param : type \n description indented on new line)" | ||
| - "Sphinx format (:param [my_param]: description)" |
There was a problem hiding this comment.
The parameter formatting may be more easy to recognize. Alternatively can we have links (e.g. to https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html) or maybe a small sample page that we generate.
I can imagine people use one of the styles without knowing how it's named. I think we are more interested in actual usage of the formats rather then whether the people know how their used format is called.
| @@ -268,7 +268,7 @@ questions: | |||
| - "Sphinx Book" | |||
| - "Sphinx Bootstrap" | |||
| - "Sphinx Immaterial" | |||
| - "Something else/I don’t know" | |||
| - "I don’t know" | |||
There was a problem hiding this comment.
"Something else" is already covered by the other option. - And it's important to distinguish "I don't know" from other answers.
|
cc @isabela-pf (I can't request a review) |
Not necessarily. |
|
Yes, if people do not use sphinx. But given the survey comes from the sphinx ecosystem, I anticipate we'll have a strong bias towards sphinx users and that both questions will have a very similar answer distribution. Or am I overlooking something? |
|
If you're not using sphinx, answering the "Why did you choose the engine you use for your documentation?" question is valuable in itself. If you are using Sphinx, then we may want to know more. Maybe just the title of the question can be tweaked, as the comment says it all: This question is about figuring out what is the value that people see in using Sphinx. Maybe you got there because others were already using it, but now you stick to it because of the extensions ecosystem. I think that's valuable information. |
|
Also, some folks use more than one documentation engine. I know of at least a few that do this, as some features they needed for projects were unavailable in Sphinx or other reasons deemed other documentation engines better suited for their use case. These are also valuable data points; if we end up having a good overlap between both questions' answers, it is fine, but I'd rather not make an a priori assumption that all of the respondents use Sphinx only. |
| - "usability issues, e.g. unclear error messages" | ||
| - "Insufficient documentation" | ||
| - "Sphinx breaks too often on new releases" |
There was a problem hiding this comment.
Notice that adding more options will also require tweaking the Title for this question as they'd need to rank more than 5 items.
Additional question: Isn't "What is the main reason you use Sphinx?" duplicate to "Why did you choose the engine you use for your documentation?"