Improve Content Width Constraints in Ansible Documentation

[JeffHuss]

Improve Content Width Constraints in Ansible Documentation

Issue Description

The current Ansible documentation layout allows content to stretch across the full width of the browser window (after the Table of Contents). This creates significant readability issues, particularly on wider displays and at 16:9 resolutions.

I'm including screenshots for the issue and proposed solution (using an example) to help clarify what I'm describing.

I'm viewing the docs page with the following client configuration:

• OS: Ubuntu 24.04.2 LTS
• Browser: Google Chrome Version 134.0.6998.88 (Official Build) (64-bit)
• Window size: Full screen
• Screen resolution: 2560x1440
• Monitor size: 27"
• Zoom level: 100% (default)

Example page with the issue: https://docs.ansible.com/ansible/latest/network/getting_started/basic_concepts.html

Problems with Current Implementation

1. Excessive line length - Text lines exceed the optimal 50-75 characters per line recommended for technical documentation readability (NewTarget's analysis of optimal content width)
2. Content scanning difficulty - Wide text makes quickly finding specific information more challenging, particularly important for technical reference material
3. Inconsistent reading experience - Reading experience varies dramatically depending on window size, which does not align with WCAG 2.1 readability guidelines (W3C readability recommendations)

Proposed Solution

Implement a maximum width constraint for the main content area, similar to what's done in other technical documentation sites like Elasticsearch:
https://www.elastic.co/guide/en/elasticsearch/reference/current/data-streams.html

Supporting Design Principles

• Optimal Line Length: Research shows 50-75 characters per line (approximately 600-800px width) is ideal for reading comprehension (Readability: the Optimal Line Length - Baymard Institute)
• Eye Movement Patterns: Shorter line lengths reduce "return sweep" errors where readers lose their place between lines (Smashing Magazine on readability)
• F-Pattern Reading Behavior: Constrained width supports natural web reading patterns identified in eye-tracking studies (Nielsen Norman Group eye-tracking research)
• Responsive Design Best Practices: Content should adapt to screen size but with reasonable maximum constraints (Google Material Design Guidelines, MDN Web Docs)
• Information Hierarchy: Constrained content width helps maintain visual focus on important information (Interaction Design Foundation on Visual Hierarchy)

Additional Notes

• The solution should maintain responsiveness while implementing maximum width constraints
• Appropriate whitespace management would be needed to balance the layout once content width is constrained

This change would significantly improve the readability and overall user experience of the Ansible documentation, particularly for users of larger displays or when using the documentation for extended periods.

[ansible-documentation-bot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at #docs:ansible.im if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See the Ansible calendar for meeting details. We welcome additions to our weekly agenda items too. You can add the dawgs-meeting tag to a forum topic to bring it up at the next meeting.

[JeffHuss]

I do want to add that the documentation is WRITTEN extremely well. I love it, and it's been very useful. My issue is strictly with the page formatting. As someone who has worked as a technical writer I want to make sure I convey my gratitude for the quality of the docs.

[samccann]

Thanks @JeffHuss - I've recreated this issue at ansible-community/sphinx_ansible_theme#112, where the code exists that controls the docs theme. Will close the issue here in favor of that one.