Documentation landing page lacks call to action

jimboolio commented 1 year ago

Summary

Getting started documentation is difficult to find from the landing page if you don't know the proper terms of what you should be looking for.

Consider use case:

"I have heard what Ansible can do but don't know how to use it or how to get started with it. I have some hosting experience, so I know the best approach is the official documentation even thought there are plenty of third party tutorials."

What happens currently:

When someone lands on https://docs.ansible.com/index.html they are greeted with three main "cards" on the usual focus area where the main content usually appears. All of the three options are equally colored suggesting equal importance and they are titled with technical terms that only an experienced Ansible proressional would know the meaning of in Ansible's case.

In this case the user should know to click the first card titled Ansible Community, but unless they bother to read the description the initial impression is that this link is going to redirect them to some sort of an forum - or a community version of Ansible whatever that is, since the use case does not yet know that.

And even if they read the description they will still be confused between the first and second card since the second option sounds like it's going to give a overall picture of an ecosystem where all features of Ansible are used.

There is a card with higher visual importance and that's going to redirect the newcomer to even more choices and possibly entirely off docs.ansible.com

I did share similar use case as my example one (with the exception that I was applying for a job with Ansible in requirements), now I have used Ansible for quite much longer and in my current docs use case I know somewhat okay what those terms on the landing page mean and I am somewhat quickly able to find the correct section of the documentation, so I don't need to visit the landing page.

I think the primary function of an landing page in documentation should be to guide the novice user getting started with the documented thing in question

Suggested action for improvement

Improve discoverability of the getting started guide by adding "Get started with Ansible" card to the landing page of docs.ansible.com with a link to this page: https://docs.ansible.com/ansible/latest/getting_started/index.html . The card should have high priority in the visual hierarchy to act as the "call to action".

Issue Type

Documentation Report

Component Name

unknown

Ansible Version

ansible [core 2.14.1]
  config file = None
  configured module search path = ['/not-applicable']
  ansible python module location = /not-applicable
  ansible collection location = /not-applicable
  executable location = /not-applicable
  python version = 3.10.9 (main, Dec  7 2022, 00:00:00) [GCC 12.2.1 20221121 (Red Hat 12.2.1-4)] (/usr/bin/python3)
  jinja version = 3.1.2
  libyaml = True

Configuration

CONFIG_FILE() = None

OS / Environment

Browser (any)

Additional Information

In summary

Code of Conduct

[X] I agree to follow the Ansible Code of Conduct

ansibot commented 1 year ago

Files identified in the description: None

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

todd-placher commented 1 year ago

While a helpful suggestion, I doubt a marketing CTA will help a person looking to get started on using Ansible find the GSwA doc link. A simple search brings a dev to that page. The initial card page you're referring is more of a catalog of what is available as opposed to a learning path/Getting Started type path.

Feel free to do a PR and change the cards per: https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#editing-docs-directly-on-github to help

In the vein of your suggestion I would think a pre-req. knowledge checklist might be of more benefit on the https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#editing-docs-directly-on-github as I have often run into folks getting bogged down in a lack of the fundamentals of something NOT Ansible related while installing

samccann commented 1 year ago

Hi @todd-placher and thanks for the feedback! I transferred this issue to the repository that controls the Ansible docsite. We plan on doing significant improvements to this docsite in 2023 so this definitely helps us know where to make some important changes.

samccann commented 1 year ago

@todd-placher - we have a proposed new docsite at https://ansible.github.io/jinja-docsite/ that I think addresses this issue. Would love your feedback.

Spredzy commented 1 year ago

The new docsite is now live on docs.ansible.com - As @samccann stated, would love to hear your feedback. It is has designed to address part if not all your concerns in your original issue @jimboolio

oraNod commented 1 year ago

@jimboolio echoing what @Spredzy and @samccann have said. We'd love to hear your feedback.

We hope the new layout does a better job of guiding users directly to specific documentation related to their goals. It would be interesting to hear if the current paths we've outlined are sensible and effective. Also, while you navigate around, you might notice incomplete or missing journeys. We'd love to hear about those especially.

Cheers!

ansible / docsite