[PATCH v2 00/12] doc: improve contributing documentation clarity and style

Stephen Hemminger
2026-01-16T20:17:46Z

This patch series improves the readability and consistency of the DPDK
contributing documentation. The changes focus on editorial improvements
without altering any technical content or policies.

Initial work on this was done by Nandini Persad. This follow-up series
uses AI assistance for broader coverage across all contributing guides.

The primary improvements across this series include:

- Converting passive voice to active voice for clearer, more direct prose
- Using imperative mood for guidelines and instructions
- Removing redundant phrases ("Please note that", "It is recommended that")
- Simplifying wordy constructions
- Fixing grammar, punctuation, and typos
- Improving consistency in terminology

Summary of changes by document:

design.rst - Fix "executive environment" typo, improve clarity
abi_policy.rst - Active voice, simplify ABI change descriptions
coding_style.rst - Imperative mood for style guidance
documentation.rst - Active voice for Doxygen documentation instructions
linux_uapi.rst - Simplify uAPI header import instructions
new_driver.rst - Direct language for driver contribution process
new_library.rst - Simplify library approval process description
patches.rst - Comprehensive style improvements throughout
stable.rst - Restructure for scannability, concise backport criteria
vulnerability.rst - Active voice for security process steps
unit_test.rst - Fix grammar issues, consistent command formatting
abi_versioning.rst - Fix typos and grammar errors

These changes make the documentation more accessible to new contributors
and align with modern technical writing best practices.

v2:
- Rebased on latest main
- Incorporated additional grammar fixes in unit_test.rst and abi_versioning.rst
- Fixed inconsistent backtick usage for command references

Nandini Persad (1):
doc: correct grammar and typos in design guide

Stephen Hemminger (11):
doc: improve ABI policy documentation style
doc: improve coding style guide readability
doc: improve documentation guidelines style
doc: improve Linux uAPI header documentation
doc: improve new driver guide readability
doc: improve new library guide style
doc: improve patch submission guide readability
doc: improve stable releases documentation
doc: improve vulnerability process documentation
doc: improve unit test guide readability
doc: fix grammar and style in ABI versioning guide

doc/guides/contributing/abi_policy.rst | 194 +++++++-------
doc/guides/contributing/abi_versioning.rst | 32 +--
doc/guides/contributing/coding_style.rst | 20 +-
doc/guides/contributing/design.rst | 71 +++---
doc/guides/contributing/documentation.rst | 6 +-
doc/guides/contributing/linux_uapi.rst | 40 +--
doc/guides/contributing/new_driver.rst | 62 ++---
doc/guides/contributing/new_library.rst | 20 +-
doc/guides/contributing/patches.rst | 434 ++++++++++++++--------------
doc/guides/contributing/stable.rst | 147 +++++-----
doc/guides/contributing/unit_test.rst | 129 ++++-----
doc/guides/contributing/vulnerability.rst | 140 ++++-----
12 files changed, 637 insertions(+), 658 deletions(-)

--
2.51.0