Looking for survey question ideas on docs

Project Discussions
1

Every so often, Ansible-land runs a survey. We had some good info from the last one (gosh…2020 maybe? time flies). While it’s a general Ansible survey, we can likely put in some more docs questions.

So, what do we want to ask our intrepid readers about Ansible community docs? :slight_smile:

2

I guess this is related to What questions should be in a community survey?, which reminds me I still have to add some questions there. Some potential docs related things to ask:

  • What kind of docs do you consume / would you like to consume? Online web docs, downloadable web docs, ansible-doc output, PDFs, Dash/Zeal, …?
  • Maybe some free-text, what are you missing most in the docs? Or better a choice of options instead of free-text? (But which options? :slight_smile: )
  • What kind of docs do you use most? Module/plugin references, how-tos / scenario guides, … (please extend this list before putting it on the survey :wink: )?
1 Like
3

We should only ask if we are willing to create and maintain all these docs output types :slight_smile:

4

Discussed in the DaWGs meeting:

  • We should make the question vague, something like ‘Do you compose documentation online or offline’… that way we have flexibility on the solution if we have a significant number of people wanting offline docs.
  • Add a question about the documentation journey pages on docs.ansible.com (those html pages you hit before you get to a docsite for a project).
1 Like
5

Thanks for organizing this @samccann Some possible questions from my side:

  • Which of the following docsite “personas” do you think describes you the best? Someone getting started with Ansible, an Ansible user, module or plugin developer, community maintainer.
  • Would you say you’ve completed any of the “journeys” on docsite pages such as Users | Ansible Documentation or Developers | Ansible Documentation? If so, which ones?
  • In the docsite journeys do you think there are any steps or information missing or incomplete?
  • Do you find the “Quicklinks” section of the docsite pages helpful?
  • If you could change any of the “Quicklinks” which ones would you change and how?
  • For developers, can you successfully find all or most of the help you need for using things like sanity tests from the Ansible documentation?
  • Do you have any suggestions on how we could improve the Developer Guide at Developer Guide — Ansible Community Documentation
  • Is there anything you really don’t like about the Ansible community documentation?
  • Do you know you can search across all the Ansible projects hosted on ReadTheDocs?
  • Have you been able to find help across multiple Ansible docsites?
  • Do you rely on the Porting Guides in one or more of your projects?
  • Have you ever encountered linter issues after following recommendations from the Ansible docs?

I’ll try to think of some more questions. Maybe we could phrase these ones better too. Could possibly be too vague in some cases or leading in others.

1 Like
6

This one should be fun since we get dinged regularly because our docs don’t comply with ansible-lint default rules :slight_smile:

Thanks for the list of question ideas!