Mapping user journeys for the Ansible docsite

[oraNod]

Summary

The Ansible community team has started efforts to improve the user experience for the docsite "docs.ansible.com" and seeks opinions and assessments from the Ansible community. We want to ensure that our efforts are community driven and focused.

Recently we've made the docsite repository public. We've also made a number of changes to the existing docsite, notably:

• Refreshed the index page to make the community theme more prominent and update the wording on the subheading and on each card.
• Updated the cards on the ansible_community.html page.
• Added the ecosystem page.

As we look to the year ahead there is work ongoing to identify personas and map user journeys. That effort ties into other efforts to modernize the Ansible docsite and provide much better navigation and content discoverability. There's also some overlap with broader changes to ansible.com.

With this topic I'd like to ask: What changes would the Ansible community like to see on the docsite?

• this includes adding links to docsites that you feel are doing things 'right' that we can go learn from etc.

[oraNod]

One place I'd like to start with this is the existing collections.html page.

I feel like we should include more community docs on the collections page, (like the community.dns guides). Is that acceptable? What other docs should we make available under collections?

[samccann]

I'm less inclined to add more collections to that page. I'd rather see the page disappear personally. If we do decide to highlight individual collections, how do we decide which ones?

We decided some time back to move all collection-level guides into their individual collection, which means the cloud/virtualization tab on that page will need to go as well.

[samccann]

Summary from DaWGs meeting discussion -

• need more step by step content for new users. Something that covers tags and strategies, and things like 'change_when' and 'failed_when' etc. A full end to end tutorial starting with ansible -m ping for example.
• Ask on the user channel to see what ideas come there as well.
• For advanced users, the current docs work well, but for example, if you don't know you can add tags, you aren't even aware to search for that option. Someone with a big role that takes ages to run, doesn't have the concept that they can run a subset of their roles by using tags, for example.
• should we revampe the 'deeply commented example playbook' from https://github.com/phred/ansible-examples/blob/master/pedantically_commented_playbook.yml to show every possible option in use, and include links directly to the docs for that particular keyword etc.

[oraNod]

@samccann

Those are good points and I think we should consider breaking each of them out into docs issues, similar to ansible/ansible-documentation#80. I don't mind doing that if you agree. Then we can add them to our plans for the year ahead.

The thing about looking at users and trying to map content to journeys means you start to see the gaps. It's then a bit of a chicken/egg situation with ensuring users can efficiently find the content they need.

The deeply commented example playbook is great and all but the last one hasn't had a commit since 2012. I feel like those all-in-one docs are always a big effort with a brief shelf life. Plus it's mostly reference content, of which there is already plenty. Is there a way to generate a full reference from the codebase?

As for the collections page, maybe we shift the focus to developing collections and the work that @Andersson007 is doing with the community? Maybe the docsite should have more details about the process for including collections and so on?

[samccann]

@oraNod - Github has a way to create one issue, add a task list, and then turn each 'task' into an issue. That way they are all linked to a general 'improve user experience on docs' epic so to speak. So that would be my recommendation - start an issue in ansible/ansible and put each item as a checkbox task. Then when we have everything that comes out of this topic listed, we can start turning them into linked issues.

As for the deeply-commented example playbook - yes, it's old/unmaintained but if docs takes it over, we have a better chance of keeping it maintained. I personally love me a good self-documenting example, whether it's config or in this case a playbook. It doesn't replace docs for sure, but it does give people a great overview of the things you can do with a playbook.

For collections - we do have collection contributor stuff that Andrei wrote, and a batch of other collection contributor details still here and here. and the maintainers stuff here. Those would be good additions to the collections.html page I think.

[Andersson007]

• If i got blind, sorry, i don't see Collections on the ecosystem page https://docs.ansible.com/ecosystem.html Taking it personal:))) Should be at the top, imo:)

I feel like we should include more community docs on the collections page, (like the community.dns guides). Is that acceptable?

I don't think we should put docs of individual collection on that page as we have 100+ collections included, can be noisy

What other docs should we make available under collections?

• Maybe Quick-start guides and Maintainer guidelines i mentioned in that comment?
• Maybe also contributor path and steering committee info?

Content on https://docs.ansible.com/collections.html can also be divided into several subsections (not sure how to call them):

1. For users
2. For contributors (will contain those guides i mentioned about and maybe something else)
3. For collection maintainers (will contain those maintainer guidelines, etc.)

FYI: there's a good free tool which can be helpful for visualization of structures https://www.mindmeister.com

Ideas?

[oraNod]

@Andersson007 I thought I left a comment on this already but I guess not.

I can add Collections to the ecosystem page but I want to make it more prominent. This is just a start so plz don't take it personally, lol. I totally agree that the Collections part of the docsite needs to be improved. As you say having a page with 100+ collections would be noisy and difficult to maintain.

Last week I had a pass at putting together docsite personas, one of which is "Collection maintainer". I'd love feedback / thoughts: https://hackmd.io/pZb5w5JFRQW3RJ73n23tlw?both#/

I also made an attempt at a new layout for docs.ansible. I tried mindmeister but it didn't do quite what I needed so ended up using Miro. TL;DR I can export the board I'm working on as a jpg until I find a better open-source alternative.

[oraNod]

I think we can use Jinja templates for different cards and generate HTML. As we work through we can refine the personas and map out workflows more clearly.

[oraNod]

As a next step on the path to a new and improved Ansible docsite we want to hear from the community. We've narrowed down a set of key personas that we plan to use to create better entry points to Ansible documentation. The goal is to help community users find docs in a way that fully supports their automation journey. Please add your thoughts in the thread or comment directly on the personas at: https://hackmd.io/pZb5w5JFRQW3RJ73n23tlw?both#/

[Andersson007]

I left a comment near AWX/Galaxy operations in the personas doc but I'm putting it in here because it seems important to me.

How about generalizing the personas?
Shouldn't we determine categories applicable to any of sub-projects (or to any piece of open source software)?
For example, we could have:

• novice
• creator/user
• developer
• owner/maintainer
• community contributor/member/evangelist
• ...

This structure would be applicable to any project like: Ansible, AWX, Molecule, ..., ...
Otherwise, imo, we're mixing notions of different levels in one pot.
Based on the general categorization, we could structure docs of all of the subproject same way on docsite.
Let's abstract from concrete project for now and develop a very general high-level framework.

[Andersson007]

To visualize the above proposal:

[oraNod]

@Andersson007 I agree and think that personas do extend to projects. For a docs framework I suggest Diataxis. What I see missing in that visualization is the user journey. It appears to be more project focused, but that's not where the user starts.

I see something like this:

[oraNod]

When it comes to the framework for project docs Diataxis gives an approach for mapping content types to the journey.

[Andersson007]

@oraNod

What I see missing in that visualization is the user journey. It appears to be more project focused, but that's not where the user starts.

It is missed deliberately in the visualizaton as well as a lot of other stuff.
Let's maybe develop the abstract structure of the top level first. Then, when the structure is designed and approved, we could go further, deeper, defining details, etc.
I would avoid thinking about everything at once:)

[oraNod]

@Andersson007 Sorry if I'm totally not getting it. Can you explain more about what you mean by "top level structure"?

[samccann]

So one thing to keep in mind - This docs.ansible.com page discussed here is just the first page on docs.ansible.com. The goal is to help the reader on their journey to the actual documentation bits they need. So I think @oraNod has a good structure to start that journey, but we do have to ensure that journey matches across all the sub projects (part of @Andersson007 's point I think). So today, the novice user needs to understand ansible (core) before they can get into other projects like ansible-lint or ansible-navigator.
So I envision the need for a few more html pages that are 'below' this one so to speak. This first page should cover the start of multiple journeys - for the user (new or experienced) for the contributor or those looking to get involved in the Ansible community, and for the developer. From there, we need directions for people interested in 'other stuff'.

Our goal on this first page is to ensure we are covering the needs for 80% of our site visitors. So that is the first question we need to answer, and unfortunately, web analytics can only get us so far. Today, people come to docs.ansible.com for core, Ansible package (including collections) and ansible-controller (aka tower). Historically, that's the only docs available. Now we have an ecosystem with a ton of other docsets linked to it, but not enough web traffic yet to see which projects are top priorities for our expanding readers. So we need the community to tell us whether one or more of these other projects (other than ansible-lint) need 'front page' presence.

I see two points here to consider:
1 - What DOES the entry-point look like for someone who knows ansible (core) but wants to start using some other tools like ansible-navigator? Maybe this is a page below this current 'front page' proposed for docs.ansible.com
2 - Defining a per-project 'flow' like @Andersson007 comment has. I see that as the docSET flow (meaning once I land on ansible docs, or ansible-navigator docs, or ansible-rulebook docs , they should all have a common flow that matches something like Andre's visualization - it must have a new user section, a contributor section, etc etc).

[Andersson007]

@Andersson007 Sorry if I'm totally not getting it. Can you explain more about what you mean by "top level structure"?

@oraNod I think Sandra's comment reflects it

1 - What DOES the entry-point look like for someone who knows ansible (core) but wants to start using some other tools like ansible-navigator? Maybe this is a page below this current 'front page' proposed for docs.ansible.com

Regardless where the ecosystem ends up, it imo should be redesigned to group related subprojects, otherwise, as is now, it's noisy and require long scrolling down

Giving each project a personal box is imo too generous considering limited space and the number of projects, and it makes things hard to find and finger tired of scrolling.

I suggest grouping them, for example, there will be several boxes with titles like Ansible, Tools, Operations, etc. containing links like depicted below (not behind but on the same page):

Those boxes schematically would look like

-----------------------------------       ----------------------------------
|           Ansible               |       |           Tools                |      .......
-----------------------------------        ---------------------------------
| Core                            |       | Lint                           |
| Collections                     |       | Molecule                       |
-----------------------------------       ----------------------------------

[oraNod]

@Andersson007 I see now, thanks! That looks great to me too. And I agree with you. The existing cards take up far too much "real estate" and fall into that same paradigm of being too project oriented. I definitely feel like this is the right direction for that ecosystem page.

[oraNod]

@Andersson007 We should also speak with @ssbarnea about his plans for a devTools site. However that evolves we should be sure that we move forward together.

[Andersson007]

This docs.ansible.com page discussed here is just the first page on docs.ansible.com. The goal is to help the reader on their journey to the actual documentation bits they need.

Got it

So I envision the need for a few more html pages that are 'below' this one

Definitely, see below

Our goal on this first page is to ensure we are covering the needs for 80% of our site visitors.

We imo have two main entities:

• Personas (Novice is a special case which means an absolutely new person)
• Projects

So because we have two entities ^, we need at least two layers of pages: the top and the next.
The options imo are:

• Top level: personas, next layer: projects. I.e., any persona if you click it has a list corresponding projects behind.
• Top level: projects, next layer: possible personas

It's not fair imo to other project, if, say, Creators/Users will point directly to Ansible guides (only). There are different kinds of users possible: ansible collection user, navigator user, EE user, AWX user, etc.
Novice is a special kind of personas for absolute newcomers, so it can contain a linear path.

It's just another option to consider (depicted in blue imo should have all projects listed where a persona can be):

[samccann]

@Andersson007 We should also speak with @ssbarnea about his plans for a devTools site. However that evolves we should be sure that we move forward together.

My nickel - any devTools site should really be a part of docs.ansible.com if possible. Feels too important to have it somewhere else so to speak, tho the individual tools (lint etc) exist well on their own.

[mariolenz]

I'm not a UX expert, but:

We imo have two main entities:

• Personas (Novice is a special case which means an absolutely new person)
• Projects

So because we have two entities ^, we need at least two layers of pages: the top and the next. The options imo are:

• Top level: personas, next layer: projects. I.e., any persona if you click it has a list corresponding projects behind.
• Top level: projects, next layer: possible personas

I would start with "topics" (what you called projects), and then have the experience ("persona") at the next level. This way, people can jump to what they're interested in an then decide what level they want to have a look at it.

Makes more sense to me. But that's just my personal preference.

[oraNod]

@Andersson007 Yeah I think that could work nicely if we had a secondary page that each persona card "jumps" to. Maybe like this:

This could tie in quite well with some of the things that the dev tools team have in mind too. Anyway I think it makes a lot of sense to go with your first option, top level: personas, next layer: projects.

I suppose my view is a little contrary to what @mariolenz has suggested. However I think putting the personas on the top-level, as you say, helps keep focus on the user journey rather than the underlying technology itself.

[samccann]

I also prefer the personas first so to speak at the top level. the problem with listing projects first is only the experts know which project they are interested in. That said, we should include a quick link on that first top-level page so those advanced readers have only one click to get to a page that lists everything (similar to the current ecosystem page, but not with all those big spacy boxes as they take up too much room).

[samccann]

Just a bit of statistics fun for the docsite for 2022:

• unique visitors overall - 3.5M
• visitors to docs.ansible.com (this top-level page) - 288K (approx 8% of traffic)

[Andersson007]

@mariolenz @oraNod @samccann thanks for the feedback!
Points from your recent comments i see worth summarizing separately are:

• putting the personas on the top-level helps keep focus on the user journey rather than the underlying technology itself
• the problem with listing projects first is only the experts know which project they are interested in
• we should include a quick link on that first top-level page so those advanced readers have only one click to get to a page that lists everything (similar to the current ecosystem page, but not with all those big spacy boxes as they take up too much room)

[Andersson007]

Feedbak on the docsite personas.

Considering the discussion above, from my perspective:

• Novice: is fine
• Content creator: should it be renamed to just Users ? Rationale:
  • we can use Ansible not creating any content, e.g. when running ad-hoc commands, just click buttons in AWX WebUI, launching playbooks created by someone esle, etc.
  • also the word "content" in general seems a bit confusing to me as it's imo too broad and diverse. When i saw it the first time, the "content of what? docsite/blog/collection maybe" question popped up.
• Operations: should it be treated as a subcategory of User, i.e. to remove it entirely as the second layer will list the projects and AWX and others will be listed there.
• Collection owner/maintainer: to rename to Project owner/maintainer as we seem to agree that the second layer for each persona will list the projects.
• Ansible developer: to rename it to just Developer to make it more general? See the previous points.
• Community member/contributor: to rename to Community member/Evangelist as contributor can confuse a bit. And it overlaps with Developer
• I'm not sure if we should create a separate persona for Doc contributions or put it under Developer category?
• Maybe the top page could also contain a box called, say, Contribution overview or something containing a link to a page describing contribution ways w/o any project-specific details. Ideas?

[samccann]

We do have a problem with developer overlapping with contributor, even in our current guides. That said, we can't have a front page that has nothing for how to join the community. So I would vote for community member/Evangelist to cover the general 'join the community!' call to action. And under that tab 'somewheres' we would point people to different places based on whether they are looking for meetups/blogs/forums, or 'contributing to the project' (with contributor being specific to github involvement).

[Andersson007]

We do have a problem with developer overlapping with contributor, even in our current guides. That said, we can't have a front page that has nothing for how to join the community. So I would vote for community member/Evangelist to cover the general 'join the community!' call to action. And under that tab 'somewheres' we would point people to different places based on whether they are looking for meetups/blogs/forums, or 'contributing to the project' (with contributor being specific to github involvement).

@samccann ^ SGTM

[oraNod]

Operations: should it be treated as a subcategory of User, i.e. to remove it entirely as the second layer will list the projects and AWX and others will be listed there.

@Andersson007 This makes a lot of sense to me for the docsite navigation. I do think we want to have a distinct Operations persona because they have specific content needs.

[oraNod]

Content creator: should it be renamed to just Users ? Rationale:

@Andersson007 Yeah this makes a lot more sense to me now. Full disclosure the "creator" persona is something that came from downstream originally. It's more like another step on the user journey, not a persona on its own. Thanks for helping identify that. Just the sort of feedback I think this needs.

Also ack to the word "content" being too vague. I suppose it is condense which is useful for headings but we should always say what that means somewhere.

[Andersson007]

Speaking about the vote,
we / I could try to create a final block scheme for the first two layers with a rough list of personas based on #175 (comment) and other comments tomorrow or on Monday (just those two layers w/o any further references, details).
Then we could offer the community to vote on that scheme.
We could discuss it tomorrow if you have time.

We could do the whole work in the following stages:

1. Designing that first-2-layers scheme (rough personas -> projects) as described ^
2. Presenting it (the high level concept) to the community for review
3. Vote: getting it approved/rejected by the community UPDATE: let's maybe just discuss it?
4. Filling out the approved scheme with concrete personas (which we'll continue to define now)
5. Presenting it to the community for review
6. Vote UPDATE: let's just discuss, otherwise we'll need to vote on any doc change

If it feels like too many votes, we could conduct only the final one

[Andersson007]

Speaking about "Collection owner/maintainer" / "Community project owner maintainer":

• I created a topic to collect feedback from the community which card ^ it should be docs.ansible.com: projects besides collections we can put behind the "Project owner/maintainer" persona card #193
• For collection maintenance card (regardless whether it's on the homepage or at the second layer), we could just put a link to https://docs.ansible.com/ansible/devel/community/maintainers.html behind. I'll polish it a bit right now but it's generally ready.

[Andersson007]

Possible Developer -> Collections card items to start with:

1. Prerequisites: what you need to know before getting started.

2. Good first issues in Collections: chose one and use the Quick-start development guide to learn by doing.

3. Developer Guide: to learn how to develop your custom module or plugin and to learn general information about Ansible development.

4. Ansible Collection Contributor Guide: to learn collection-specific development scenarios.

5. Ansible Documentation Style Guide: to learn how to create clear, concise and useful documentation for your code.

6. Contributor Path: to learn more contribution options.

A question to anyone, is there anything else we should add/change/remove from here ?

[oraNod]

@Andersson007 Those suggestions look good to me. What do you think about adding them to the jinja docsite so folks can see what you mean in action? It might be better to get feedback if we can contextualize the ideas.

https://github.com/ansible/jinja-docsite

[mariolenz]

I'm afraid ansible/ansible#189 ended without getting any votes except from @Andersson007. Since it's been announced to end on 2023-02-08, I've closed it.

Sad but true. But if we give an end date for a vote, I think we should eat our own dog food and stick with it.

[oraNod]

@mariolenz Thanks for closing that one. I agree with you. Honestly I'm not sure if I should have called for a vote or not because we'll be working on the personas and user journeys for a bit longer. We mainly wanted to bring the effort to the community and ensure everyone is ok with it. Hopefully we achieved that at the Contributor Summit on Wednesday. Cheers.

[oraNod]

Note that we've moved the personas to GH here: https://github.com/ansible/docsite/blob/personas/personas/ansible-docsite-personas.md

And the user journey maps are here: https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md

[mariolenz]

The Ansible community team has started efforts to improve the user experience for the docsite "docs.ansible.com" and seeks opinions and assessments from the Ansible community. We want to ensure that our efforts are community driven and focused.

FYI @GregSutcliffe proposed to move the community stuff to a new domain: ansible/ansible#201

I'm not sure if or how this will impact the discussion here. But I wanted to let you know, in case you haven't seen it.

BTW, feel free to comment on the suggestion. Up until now I'm the only one who did hint hint

[samccann]

Closing this - the journeys are at https://github.com/ansible/docsite/tree/main/data/journeys for future reference. Thanks everyone!

[oraNod]

Thank you @samccann