Skip to content

Conversation

madebydna
Copy link
Contributor

@madebydna madebydna commented Feb 11, 2025

Proposed changes

Problem: The "Creating Amazon EC2 Instances" was last updated about 6 years ago and has fallen out of date with the current flow of creating EC2 instances on AWS. The screenshots and some of the links were outdated. The page did also not comply with Hugo formatting standards, and the current style guide. The Hemingway editor's readability score was 8.

Solution:

  • followed instructions in the guide to create an AWS EC2 instance and install NGINX Open Source on it using Ansible
  • updated instructions and screenshots to match the current AWS EC2 creation flow
  • reduced the number of screenshots
  • made sure to use Hugo formatting for links, and screenshots
  • improved the readability score to a 6
Screenshot 2025-02-10 at 7 22 45 PM

Testing: Followed the instructions in the guide to make sure they work and reflect the current AWS UI flow.

Please focus on (optional):

  1. I placed the images in static/img/ as instructed in the Contributing docs. Should I remove the old screenshots linked in the original version of the article?
  2. I removed the section about other configuration management tools like Chef and Puppet since the links were broken and I could only find the articles on the Korean version of the F5 site (e.g. Installing NGINX and NGINX Plus with Chef). I can add the section back if linking to that site is okay, though.

Closes #99

Checklist

Before merging a pull request, run through this checklist and mark each as complete.

  • I have read the contributing guidelines
  • I have signed the F5 Contributor License Agreement (CLA)
  • I have ensured that documentation content adheres to the style guide
  • If the change involves potentially sensitive changes, I have assessed the possible impact
  • If applicable, I have added tests that prove my fix is effective or that my feature works
  • If applicable, I have checked that any relevant tests pass after adding my changes
  • I have updated any relevant documentation (README.md and CHANGELOG.md)
  • I have rebased my branch onto main
  • I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

@madebydna madebydna requested a review from a team as a code owner February 11, 2025 04:03
Copy link
Contributor

@ADubhlaoich ADubhlaoich left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes generally LGTM: I may do a second pass in the interim period waiting for another TW to take a look.

With regard to your questions:

  1. Yeah, might as well just delete the old ones.
  2. I think leaving out the section is fine. We haven't localised the documentation, so having a section with broken links whose only substitute is not in English hurts the overall flow of the document.

Since you're looking at general improvements beyond correcting text, the archetypes I migrated into the repository might be of interest:

https://raw.githubusercontent.com/nginx/documentation/refs/heads/main/archetypes/default.md

We have some standardized page-level information architecture we're slowly applying to pages as we work on them.

@madebydna
Copy link
Contributor Author

@ADubhlaoich I deleted the unused images and updated the list styles to take advantage of Hugo's automatic enumeration.

Regarding the default archetype, I wasn't sure if for instance the metadata in the archetype represents a new default, or if I should override it with the specific settings in this article. For instance, the archetype has toc: false while this article has it set to true. Let me know if I should make some additional changes to bring the article more in accordance with the archetype.

@ADubhlaoich
Copy link
Contributor

ADubhlaoich commented Feb 12, 2025

The archetype shows the new "defaults" in terms of what parameters each document should have and what the precise ordering is.

description: Create Amazon Elastic Compute Cloud (EC2) instances for running NGINX
  Open Source and F5 NGINX Plus.
docs: DOCS-444
doctypes:
- task
title: Create Amazon EC2 Instances for NGINX Open Source and NGINX Plus
toc: true
weight: 600

The only strictly necessary fields are title and weight: the former is the page title, while the latter affects the ordering of pages or folders that the page is part of.

  • description is used for SEO metadata: it's not actually visible within documents, but might appear as part of results in a search engine
  • docs is used as part of a cataloguing system. Every document has a 1:1 relationship with a docs code whose vale is formatted as DOCS-<some-number>.
  • doctypes is completely deprecated and was never used.
  • toc determines if a document will generate a table of contents or not - 'false' by default. It's included in the archetypes for the sake of letting someone writing a document be aware it's an option.

For this document, you'd re-order the fields, throw the doctypes line into oblivion and add type: how-to and product: NGINX+. description can go between weight and toc.

The product value is determined by where the document lives, not what the subject focus is for the text. The distinction is important, 'cause you'll sometimes see information related to one project inside the documentation for another.

@madebydna
Copy link
Contributor Author

@ADubhlaoich thanks for the detailed explanation and guidance. I updated the metadata to match the new default archetype.

Copy link
Contributor

@travisamartin travisamartin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! Thanks for the edits 😊

Approved with some suggested style tweaks.

madebydna and others added 2 commits February 15, 2025 14:46
Co-authored-by: Travis Martin <33876974+travisamartin@users.noreply.github.com>
@ADubhlaoich ADubhlaoich enabled auto-merge (squash) February 17, 2025 15:27
@ADubhlaoich ADubhlaoich merged commit 85c65cd into nginx:main Feb 17, 2025
2 checks passed
@mjang mjang added community and removed in review labels Feb 18, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Analyze NGINX Plus Deployment Guide: EC2 Instances for NGINX Open Source and NGINX Plus
5 participants