Proofread docs in the /operation directory #1710

teslazonda · 2025-11-19T11:55:25Z

Change Summary

Edited content in the docs/operation directory to align with the Microsoft Writing Style Guide

boot-options.rst
information.rst
upgrade-recovery.rst
raid.rst
password-recovery.rst

Related Task(s)

TBD

Related PR(s)

Backport

Checklist:

I have read the CONTRIBUTING document

teslazonda · 2025-11-19T11:59:01Z

docs/operation/information.rst

+recent Linux distributions.

-For additional details you can refer to https://vyos.dev/T2490.
+For details, see  https://vyos.dev/T2490.


This issue was resolved in 2020. Is the above content still relevant?

teslazonda · 2025-11-19T11:59:26Z

docs/operation/information.rst

-  .. note:: If a device is unplugged and re-plugged it will receive a new
-    Port, Dev, If identification.
+  .. note:: If a device is unplugged and plugged in again, it is assigned a new
+    ``Port``, ``Dev``, and ``If``.


What do Dev and If stand for?

teslazonda · 2025-11-27T22:21:09Z

docs/operation/password-recovery.rst

 #################

 Using the console, restart the VyOS router. The GRUB menu appears.
-Select the relevant option from the GRUB menu and press Enter.


Is this password recovery flow still accurate?

sever-sever · 2025-11-28T12:12:31Z

docs/operation/raid.rst

+Standard installation on a single disk 
 ------------------------------


There should be

Standard installation on a single disk --------------------------------------

Copilot

Pull request overview

This PR proofreads and improves documentation in the /docs/operation directory to align with the Microsoft Writing Style Guide. The changes focus on improving clarity, consistency, and readability across five operation documentation files while updating the last proofread dates to November 2025.

Standardized UI element formatting using bold text (e.g., Yes, No, Enter)
Improved sentence structure and readability throughout the documentation
Updated terminology for consistency (e.g., "RAID-1" to "RAID 1")
Enhanced descriptions with clearer, more concise language
Added proper section cross-references and updated metadata

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
`docs/operation/upgrade-recovery.rst`	Improved readability of upgrade recovery feature documentation, clarified timeout behavior, and wrapped long lines for better formatting
`docs/operation/raid.rst`	Extensive revisions to RAID 1 documentation including terminology standardization, UI element formatting, section header updates, and improved procedural instructions
`docs/operation/password-recovery.rst`	Minor improvements to password recovery instructions with updated UI element formatting and clearer action descriptions
`docs/operation/information.rst`	Enhanced system information command documentation with updated examples, improved USB device descriptions, and added VyOS 1.5 release train information
`docs/operation/boot-options.rst`	Simplified boot option instructions with clearer warnings and more concise procedural steps
`docs/_locale/{uk,pt,ja,es,de}/operation.pot`	Updated translation files to reflect changes in UI element formatting from quoted text to bold text

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-28T12:14:55Z

docs/operation/boot-options.rst

+VyOS provides several kernel command-line options to modify the normal boot
+process.
+To add an option, select the desired image in the GRUB menu at load time.
+Type **e** to edit the first line, then type **Ctrl+x** to boot.


[nitpick] Inconsistent keyboard key notation. Line 17 uses "Ctrl+x" with a plus sign, but this is inconsistent with standard documentation practices. The Microsoft Writing Style Guide recommends using "Ctrl+X" (with capital X) for keyboard shortcuts. Additionally, verify consistency with other keyboard notations in the document (line 17 uses "e" which should also be consistent).

Suggested change

Type **e** to edit the first line, then type **Ctrl+x** to boot.

Type **e** to edit the first line, then type **Ctrl+X** to boot.

Copilot · 2025-11-28T12:14:55Z

docs/operation/raid.rst


-Installation Implications
+Installation implications
 =========================


Inconsistent section header capitalization. According to the Microsoft Writing Style Guide, sentence-style capitalization should be used for headings. Change "Installation implications" to match the capitalization style used in other section headers like "Configuration".

Suggested change

=========================

========================

Copilot · 2025-11-28T12:14:56Z

docs/operation/raid.rst

 =============

-Single disk, install as normal 
+Standard installation on a single disk 


Inconsistent section header capitalization. The header should use title case for consistency with other sections. Change "Standard installation on a single disk" to "Standard Installation on a Single Disk".

Suggested change

Standard installation on a single disk

Standard Installation on a Single Disk

Copilot · 2025-11-28T12:14:56Z

docs/operation/raid.rst

+* If you do not want to configure RAID 1 mirroring, enter **No** at the prompt.

-Empty 2+ Disk 
+Empty 2+ disk 


Inconsistent section header capitalization. The header should use title case for consistency with other sections. Change "Empty 2+ disk" to "Empty 2+ Disk" to match the capitalization style.

Suggested change

Empty 2+ disk

Empty 2+ Disk

Copilot · 2025-11-28T12:14:56Z

docs/operation/raid.rst



-Present RAID-1
+Preexisting RAID 1 configuration


Inconsistent section header capitalization. The header should use title case for consistency with other sections. Change "Preexisting RAID 1 configuration" to "Preexisting RAID 1 Configuration".

Suggested change

Preexisting RAID 1 configuration

Preexisting RAID 1 Configuration

Copilot · 2025-11-28T12:14:58Z

docs/operation/raid.rst

+4. Enter **Yes** at the prompt to retain the current VyOS configuration
+Enter **No** to delete the current VyOS configuration. 


The sentence structure is awkward and incomplete. Line 90 starts a new sentence but doesn't complete the thought clearly. Consider revising to: "4. Enter Yes at the prompt to retain the current VyOS configuration, or enter No to delete the current VyOS configuration."

Suggested change

4. Enter **Yes** at the prompt to retain the current VyOS configuration

Enter **No** to delete the current VyOS configuration.

4. Enter **Yes** at the prompt to retain the current VyOS configuration, or enter **No** to delete the current VyOS configuration.

Copilot · 2025-11-28T12:14:58Z

docs/operation/raid.rst

+   where ``RAID-1-device`` is the name of the RAID 1 device. For example, 
+   ``md0`` and 
+   ``disk-partition`` is the name of the failed disk partition. For example,
+   ``sdb2``.


Awkward line break. The text "For example, md0 and" should continue on the same line as the description. Consider reformatting to: "where RAID-1-device is the name of the RAID 1 device (for example, md0) and disk-partition is the name of the failed disk partition (for example, sdb2)."

Suggested change

where ``RAID-1-device`` is the name of the RAID 1 device. For example,

``md0`` and

``disk-partition`` is the name of the failed disk partition. For example,

``sdb2``.

where ``RAID-1-device`` is the name of the RAID 1 device (for example, ``md0``) and ``disk-partition`` is the name of the failed disk partition (for example, ``sdb2``).

Copilot · 2025-11-28T12:14:58Z

docs/operation/raid.rst

+   where ``RAID-1-device`` is the name of the RAID 1 device. For example,
+   ``md0`` and 
+   ``disk-partition`` is the name of the replacement disk partition.
+   For example, ``sdb2``.


Awkward line break. The formatting is inconsistent with examples spread across multiple lines. Consider reformatting to: "where RAID-1-device is the name of the RAID 1 device (for example, md0) and disk-partition is the name of the replacement disk partition (for example, sdb2)."

Suggested change

where ``RAID-1-device`` is the name of the RAID 1 device. For example,

``md0`` and

``disk-partition`` is the name of the replacement disk partition.

For example, ``sdb2``.

where ``RAID-1-device`` is the name of the RAID 1 device (for example, ``md0``) and ``disk-partition`` is the name of the replacement disk partition (for example, ``sdb2``).

Copilot · 2025-11-28T12:14:59Z

docs/operation/information.rst

+In the past, serial interfaces were defined as ``ttySx`` and ``ttyUSBx`` where
+``x``
+was the instance number. However, the mapping of USB-based serial interfaces


[nitpick] Awkward line break in the middle of a sentence. Line 23 breaks at "x" which creates a confusing read. Consider keeping "where x was the instance number" on the same line for better readability.

Suggested change

In the past, serial interfaces were defined as ``ttySx`` and ``ttyUSBx`` where

``x``

was the instance number. However, the mapping of USB-based serial interfaces

In the past, serial interfaces were defined as ``ttySx`` and ``ttyUSBx`` where ``x`` was the instance number. However, the mapping of USB-based serial interfaces

Copilot · 2025-11-28T12:14:59Z

docs/operation/information.rst

-interface is now directly identified by the USB root bridge and bus it connects
-to. This somehow mimics the new network interface definitions we see in recent
-Linux distributions.
+To address this issue, and because of many low-cost USB-to-serial converters


Grammar issue: "because of many" should be "because many". Remove "of" for correct grammar.

Suggested change

To address this issue, and because of many low-cost USB-to-serial converters

To address this issue, and because many low-cost USB-to-serial converters

teslazonda added 3 commits November 13, 2025 22:31

Proofread boot-options.rst

eeed7e8

Fix line length Markdown lint errors

4d123fd

Proofread information.rst

60be5b9

github-actions bot assigned teslazonda Nov 19, 2025

teslazonda changed the title ~~Proofread docs in operation directory~~ Proofread docs in the operation directory Nov 19, 2025

teslazonda changed the title ~~Proofread docs in the operation directory~~ Proofread docs in the /operation directory Nov 19, 2025

Update lastproofread date in information.rst

af8b272

teslazonda commented Nov 19, 2025

View reviewed changes

teslazonda added 6 commits November 19, 2025 22:47

Updated password-recovery.rst

99752f4

Proofread upgrade-recovery.rst

f642b7f

Fix line length linting errors

75908d2

Proofread up to Empty 2+ Disk

fa666f4

Complete proofread of raid.rst

d3c88bd

Update upgrade-recovery timeout explanation

fcf95c0

teslazonda marked this pull request as ready for review November 27, 2025 22:19

teslazonda commented Nov 27, 2025

View reviewed changes

sever-sever requested a review from Copilot November 28, 2025 12:10

Copilot started reviewing on behalf of sever-sever November 28, 2025 12:10 View session

sever-sever reviewed Nov 28, 2025

View reviewed changes

Copilot finished reviewing on behalf of sever-sever November 28, 2025 12:13

Copilot AI reviewed Nov 28, 2025

View reviewed changes

sever-sever requested a review from dmbaturin November 28, 2025 12:21

		Standard installation on a single disk
		------------------------------

	Type e to edit the first line, then type Ctrl+x to boot.
	Type e to edit the first line, then type Ctrl+X to boot.

	Preexisting RAID 1 configuration
	Preexisting RAID 1 Configuration

		4. Enter Yes at the prompt to retain the current VyOS configuration
		Enter No to delete the current VyOS configuration.

	To address this issue, and because of many low-cost USB-to-serial converters
	To address this issue, and because many low-cost USB-to-serial converters

Proofread docs in the /operation directory #1710

Are you sure you want to change the base?

Proofread docs in the /operation directory #1710

Uh oh!

Conversation

teslazonda commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change Summary

Related Task(s)

Related PR(s)

Backport

Checklist:

Uh oh!

teslazonda Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

teslazonda Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

teslazonda Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

sever-sever Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

teslazonda commented Nov 19, 2025 •

edited

Loading

sever-sever Nov 28, 2025 •

edited

Loading