Skip to content

Add suggestions to survey #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 10, 2025
Merged

Add suggestions to survey #5

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
43352fa
Add suggestions
timhoffm Apr 3, 2025
5e3eb67
Revert markup language question
AA-Turner Apr 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions surveys/sphinx-survey-2025.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,10 +174,10 @@ questions:
multiple: true
other: true
choices:
- "Google format (indented sections)"
- "Google format (my_param (type): description)"
- "Numpydoc format (my_param : type \n description indented on new line)"
- "Sphinx format (:param [my_param]: description)"
Comment on lines +177 to +179
Copy link
Contributor Author

@timhoffm timhoffm Apr 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- "Markdown"
- "Numpydoc format (underlined sections)"
- "Sphinx format (reStructuredText)"
- "I don’t know"

# Motivation: Reflect on priorities for documentation in general.
Expand Down Expand Up @@ -268,7 +268,7 @@ questions:
- "Sphinx Book"
- "Sphinx Bootstrap"
- "Sphinx Immaterial"
- "Something else/I don’t know"
- "I don’t know"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Something else" is already covered by the other option. - And it's important to distinguish "I don't know" from other answers.


# Motivation: Explore patterns in Sphinx output priorities. This might be useful for contextualizing other answers.
- title: "In which formats do you publish your documentation with sphinx?"
Expand Down Expand Up @@ -297,7 +297,9 @@ questions:
- "No native support for Markdown"
- "Performance issues"
- "reStructuredText syntax is too complicated"
- "Sphinx breaks too often"
- "usability issues, e.g. unclear error messages"
- "Insufficient documentation"
- "Sphinx breaks too often on new releases"
Comment on lines +300 to +302
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Notice that adding more options will also require tweaking the Title for this question as they'd need to rank more than 5 items.

- "Sphinx is missing features I want"

# Motivation: Explore patterns in what people using Sphinx struggle with.
Expand Down