[RFC PATCH] docs: add blurb about target audience to maintainer-profile

[RFC PATCH] docs: add blurb about target audience to maintainer-profile

[Vegard Nossum]

It's good to be clear about who the intended target audience for any
given piece of documentation is, as this will help us put new text in
the correct place. Let's encourage submitters to state it explicitly
rather than relying on where they placed it in the directory hierarchy
as there isn't necessarily a one-to-one correspondence between them.

Target audience: documentation contributors and reviewers.

Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/doc-guide/maintainer-profile.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/doc-guide/maintainer-profile.rst b/Documentation/doc-guide/maintainer-profile.rst
index 755d39f0d407..db3636d0d71d 100644
--- a/Documentation/doc-guide/maintainer-profile.rst
+++ b/Documentation/doc-guide/maintainer-profile.rst
@@ -27,6 +27,13 @@ documentation and ensure that no new errors or warnings have been
 introduced.  Generating HTML documents and looking at the result will help
 to avoid unsightly misunderstandings about how things will be rendered.
 
+All new documentation (including additions to existing documents) should
+ideally justify who the intended target audience is somewhere in the
+changelog; this way, we ensure that the documentation ends up in the correct
+place.  Some possible categories are: kernel developers (experts or
+beginners), userspace programmers, end users and/or system administrators,
+and distributors.
+
 Key cycle dates
 ---------------
 
-- 
2.34.1

Re: [RFC PATCH] docs: add blurb about target audience to maintainer-profile

[Randy Dunlap]

On 1/11/24 01:48, Vegard Nossum wrote:
> It's good to be clear about who the intended target audience for any
> given piece of documentation is, as this will help us put new text in
> the correct place. Let's encourage submitters to state it explicitly
> rather than relying on where they placed it in the directory hierarchy
> as there isn't necessarily a one-to-one correspondence between them.
> 
> Target audience: documentation contributors and reviewers.
> 
> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>

Acked-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/doc-guide/maintainer-profile.rst | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/doc-guide/maintainer-profile.rst b/Documentation/doc-guide/maintainer-profile.rst
> index 755d39f0d407..db3636d0d71d 100644
> --- a/Documentation/doc-guide/maintainer-profile.rst
> +++ b/Documentation/doc-guide/maintainer-profile.rst
> @@ -27,6 +27,13 @@ documentation and ensure that no new errors or warnings have been
>  introduced.  Generating HTML documents and looking at the result will help
>  to avoid unsightly misunderstandings about how things will be rendered.
>  
> +All new documentation (including additions to existing documents) should
> +ideally justify who the intended target audience is somewhere in the
> +changelog; this way, we ensure that the documentation ends up in the correct
> +place.  Some possible categories are: kernel developers (experts or
> +beginners), userspace programmers, end users and/or system administrators,
> +and distributors.
> +
>  Key cycle dates
>  ---------------
>  

-- 
#Randy

Re: [RFC PATCH] docs: add blurb about target audience to maintainer-profile

[Jonathan Corbet]

Vegard Nossum <vegard.nossum@oracle.com> writes:

> It's good to be clear about who the intended target audience for any
> given piece of documentation is, as this will help us put new text in
> the correct place. Let's encourage submitters to state it explicitly
> rather than relying on where they placed it in the directory hierarchy
> as there isn't necessarily a one-to-one correspondence between them.
>
> Target audience: documentation contributors and reviewers.
>
> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
> ---
>  Documentation/doc-guide/maintainer-profile.rst | 7 +++++++
>  1 file changed, 7 insertions(+)

Applied, thanks.

jon