Skip to content

doc: improve contributing documentation clarity and style

Stephen Hemminger dpdk-dev 2 versions – Applied

Status from this message: Applied, thanks.

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v2 Latest12 patches 2 repliesApplied
  2. v111 patches 0 repliesSuperseded

Changes in v2 from the cover letter

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

Patches in v2 Applied

#Subject and filesSizeRepliesApplied
1/12doc: correct grammar and typos in design guidedoc/guides/contributing/design.rst+39 -321 reply
2/12doc: improve ABI policy documentation styledoc/guides/contributing/abi_policy.rst+96 -980 replies
3/12doc: improve coding style guide readabilitydoc/guides/contributing/coding_style.rst+10 -100 replies
4/12doc: improve documentation guidelines styledoc/guides/contributing/documentation.rst+3 -30 replies
5/12doc: improve Linux uAPI header documentationdoc/guides/contributing/linux_uapi.rst+19 -210 replies
6/12doc: improve new driver guide readabilitydoc/guides/contributing/new_driver.rst+31 -310 replies
7/12doc: improve new library guide styledoc/guides/contributing/new_library.rst+10 -100 replies
8/12doc: improve patch submission guide readabilitydoc/guides/contributing/patches.rst+224 -2100 replies
9/12doc: improve stable releases documentationdoc/guides/contributing/stable.rst+60 -870 replies
10/12doc: improve vulnerability process documentationdoc/guides/contributing/vulnerability.rst+65 -750 replies
11/12doc: improve unit test guide readabilitydoc/guides/contributing/unit_test.rst+60 -690 replies
12/12doc: fix grammar and style in ABI versioning guidedoc/guides/contributing/abi_versioning.rst+16 -160 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v2 yet.

Read the v2 thread

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

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(-)
Signature · 1 line
2.51.0