Re: [PATCH v3 1/7] Section 1: Introduction

[Bruce Richardson <bruce.richardson@intel.com>]

On Fri, Nov 03, 2023 at 12:01:47AM -0400, David Young wrote:
> Edited copy to be simpler based on feedback.

Thanks David,
some small comments inline below.

> ---
>  doc/guides/getting_started_guide/intro.rst | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
>  create mode 100644 doc/guides/getting_started_guide/intro.rst
> 
> diff --git a/doc/guides/getting_started_guide/intro.rst b/doc/guides/getting_started_guide/intro.rst
> new file mode 100644
> index 0000000000..538b3bacec
> --- /dev/null
> +++ b/doc/guides/getting_started_guide/intro.rst
> @@ -0,0 +1,13 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2010-2014 Intel Corporation.
> +
> +Introduction
> +============
> +
> +Welcome to the getting started guide for the Data Plane Development Kit (DPDK) covering Linux, FreeBSD, and Windows. DPDK is a set of libraries and
> +drivers that accelerate packet processing and allow the user to create high-performance
> +networking applications.

The line breaks are in odd places here. Since we track the documentation as
text files in our repository, like source-code, we want future changes to
minimise the lines being changed as much as possible.
Checking our contributors doc, I think our guidelines there for
documentation changes are out of date, so here are the "working guidelines"
I use for docs:

* line length can be up to ~100 chars, maybe a bit more if it makes sense
  to avoid breaks
* Start each sentence on a new line (unless you have two really short ones
  that both fit on one line!)
* When breaking a sentence across two lines, split at a punctuation mark,
  like a comma, or before an "and" or "but" etc. Each clause should be on a
  single line where possible.

> +
> +The guide is structured to provide basic step-by-step instructions with OS-specific instructions for each operating system where necessary. 

should we add "got setting up and using DPDK" after "instructions"?

for the OS-specific instructions, should be say that they are "only" where
necessary, to try and emphasise we have things as common as possible?

> +By the end of this guide, you should have a solid understanding of how to implement and
> +use DPDK in your networking projects, regardless of the operating system you are using.
> \ No newline at end of file

Please fix this little warning. POSIX standard specifies that all text
files should end with a newline character. Rather than having to add it
manually, many editors have a setting to ensure it is there automatically,
so that might be worth investigating.