Skip to content
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.

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

WIP: DOCS - shorten Scenario Guides, incorporate VMware Guide #53569

Open
wants to merge 44 commits into
base: devel
from

Conversation

Projects
None yet
5 participants
@acozine
Copy link
Contributor

acozine commented Mar 8, 2019

SUMMARY

Incorporates VMware content into Scenario Guides section.
Removes unused VMware pages from local TOC.
Updates main TOC for cleaner navigation.

ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

docs.ansible.com

@acozine acozine added the WIP label Mar 8, 2019

@ansibot

This comment was marked as resolved.

Copy link
Contributor

ansibot commented Mar 12, 2019

The test ansible-test sanity --test docs-build [explain] failed with 1 error:

docs/docsite/rst/scenario_guides/guide_cloudstack.rst:0:0: not-in-toc-tree: document isn't included in any toctree

click here for bot help

@ansibot

This comment has been minimized.

@dagwieers

This comment has been minimized.

Copy link
Member

dagwieers commented Mar 12, 2019

I really don't like the name "Integration Guides", it doesn't cover what it is about. We are not really integrating VMware with Infoblox (or Ansible with ACI), so I doubt people will understand what is behind this menu title. We don't integrate, we manage this infrastructure. To me "Integration Guides" sounds more like something developers would be looking at.

So I think "Scenario Guides" is a better fit, or maybe "Technology Guides". Puppet calls this Managed technology. SaltStack has its different guides structured per category in the main index (i.e. Cloud, Network Automation)

Show resolved Hide resolved docs/docsite/rst/scenario_guides/guide_aci.rst Outdated
Show resolved Hide resolved docs/docsite/rst/scenario_guides/guide_aci.rst Outdated
Show resolved Hide resolved docs/docsite/rst/scenario_guides/guide_vmware.rst
.. toctree::
:maxdepth: 1
:caption: Network Integration Guides

This comment has been minimized.

@gundalow

gundalow Mar 13, 2019

Contributor

Does the main network index page want to be linked here?

This comment has been minimized.

@samccann

samccann Mar 13, 2019

Contributor

If you mean moving the main network index page to be under this Integrations sections, no. Network automatin has to stay at the highest level to remain visible. If you mean should we have a separate link somewhere on the 'network integrations guide' section to point to the network main guides..possibly yeah.

This comment has been minimized.

@gundalow

gundalow Mar 15, 2019

Contributor

Sorry, I want clear. Would it be worth adding a link to the network guides (which shouldn't move)

This comment has been minimized.

@acozine

acozine Mar 21, 2019

Author Contributor

I am in favor of the idea - generally the easier it is for a user to get to the content she needs/wants, the better, so linking between related but different content is a good idea. I'm not sure of the best way to add a link to a TOC page, but I will experiment with options.

@gundalow

This comment has been minimized.

Copy link
Contributor

gundalow commented Mar 13, 2019

Would be good to add docs/docsite/rst/scenario_guides/vmware_scenarios: *vmware into BOTMETA as well

@dagwieers

This comment has been minimized.

Copy link
Member

dagwieers commented Mar 13, 2019

Scenario Guides, User Guides, Technology Guides doesn't set people on the wrong foot like Integration Guides does. I would think that section is about developing plugins/inventories/modules to integrate some technology into Ansible. And not about managing infrastructure.

Looking at the list, probably both VMware and Networking belong to these "Technology guides". Networking calls it the "Network Automation Guide" so why not call everything "Automation Guides" ? ACI Automation Guide, VMware Automation Guide, Infoblox Automation Guide, etc...

@ansibot ansibot removed the ci_verified label Mar 14, 2019

@dagwieers

This comment has been minimized.

Copy link
Member

dagwieers commented Mar 14, 2019

Screenshot from 2019-03-14 15-37-14

:maxdepth: 2
:caption: Ansible for VMWare
:maxdepth: 1
:caption: Integrating Ansible with Other Tools

This comment has been minimized.

@dagwieers

dagwieers Mar 14, 2019

Member

I read this as Modifying Ansible to work together with other tools which is not what this content is about.

These Scenario Guides describe for different technologies (or infrastructure) how to best automate or manage that infrastructure/product.

"Tools" here is also a misnomer IMO, Ansible is a tool, but your production database is not a tool.

integrate verb
combine (one thing) with another to form a whole.
"transport planning should be integrated with energy policy"
synonyms: combine, amalgamate, merge, unite, join, fuse, blend, mingle, coalesce, consolidate, meld, intermingle, mix, intermix, incorporate, affiliate, unify, assimilate, homogenize, harmonize, mesh, desegregate; literarycommingle
"he proposes to integrate our reserve forces more closely with the regular forces"

Not sure what I have to do to get this point across...

This comment has been minimized.

@acozine

acozine Mar 19, 2019

Author Contributor

@dagwieers it's still a WIP, and your point is well taken. I searched for a term that describes all the technologies covered in this section of the docs. The word "tool" is not my favorite, but was the best catch-all term I had come up with so far.

The Scenario Guides are too numerous to appear in the left-nav. Right now with Scenario Guides as the caption and the various Guide titles below, the user can get the idea pretty easily.
If we collapse the TOC and keep the name Scenario Guides, what can we use as the Caption above it? The other sections start a pattern:
Using Ansible: User Guide
and
Contributing to Ansible: Community Guide
So what would work for the Scenario Guides section?
Managing Technology with Ansible: Scenario Guides?

This comment has been minimized.

@dagwieers

dagwieers Mar 19, 2019

Member

If the Scenario Guides cannot be at the left in full, that's fine, but I don't see what changing the name fixes. Unless we have a better name that is.

Scenario Guides
Automate and manage other technologies with Ansible

Although I think I like Automation Guides better now, but that's just a personal preference. It does allow to remove the "Automate" part from the description.

Automation guides
Manage other technologies with Ansible

This comment has been minimized.

@acozine

acozine Mar 21, 2019

Author Contributor

I think we can leave automation out anyway - if it's Ansible, it's automation by definition.

@ansibot

This comment has been minimized.

Copy link
Contributor

ansibot commented Mar 21, 2019

The test ansible-test sanity --test docs-build [explain] failed with 1 error:

docs/docsite/rst/scenario_guides/guides.rst:0:0: not-in-toc-tree: document isn't included in any toctree

click here for bot help

@ansibot ansibot added the ci_verified label Mar 21, 2019

@acozine

This comment has been minimized.

Copy link
Contributor Author

acozine commented Mar 21, 2019

As of de3198a, the left nav looks like this:
Screen Shot 2019-03-21 at 2 37 18 PM

@acozine acozine changed the title WIP: DOCS - Scenario Guides => Integration Guides WIP: DOCS - shorten Scenario Guides, incorporate VMware Guide Mar 21, 2019

@ansibot ansibot removed the ci_verified label Mar 21, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.