Grammar issue(s) in documentation

Grammar issue(s) in documentation

[Joshua Rose]

Hi all,

I just wanted to briefly point out that as a native English speaker I
found the following text significantly hard to read.

"Do not worry installing your kernel manually and thus bypassing your
distribution’s packaging system will totally mess up your machine: all
parts of your kernel are easy to remove later, as files are stored in
two places only and normally identifiable by the kernel’s release
name."[1]

I found this very hard to read. I would probably re-phrase this as
follows, but I'd be completely open - and in fact encourage - any
suggestions on the rephrasing of the excerpt.

"Do not attempt to circumvent your distribution's packaging system by
installing your kernel manually; this will likely break your machine.
Components of your kernel can be selectively removed later on.  Such
components (files) are stored in two locations, both identifiable
by the kernel's release name."


As an additional note, I'm looking for any recommendations on a good
resource on the maintenance of the Documentation/ directory.


Kind regards,
Joshua Rose

[1]: Documentation/admin-guide/quickly-build-trimmed-linux.rst

Re: Grammar issue(s) in documentation

[Matthew Wilcox]

On Tue, Mar 04, 2025 at 10:41:08AM +1100, Joshua Rose wrote:
> I just wanted to briefly point out that as a native English speaker I
> found the following text significantly hard to read.
> 
> "Do not worry installing your kernel manually and thus bypassing your
> distribution’s packaging system will totally mess up your machine: all
> parts of your kernel are easy to remove later, as files are stored in
> two places only and normally identifiable by the kernel’s release
> name."[1]
> 
> I found this very hard to read. I would probably re-phrase this as
> follows, but I'd be completely open - and in fact encourage - any
> suggestions on the rephrasing of the excerpt.
> 
> "Do not attempt to circumvent your distribution's packaging system by
> installing your kernel manually; this will likely break your machine.
> Components of your kernel can be selectively removed later on.  Such
> components (files) are stored in two locations, both identifiable
> by the kernel's release name."

I think that's the opposite of what they meant.  I understand it as:

"Feel free to circumvent your distribution's package manager as it's
easy to remove the kernel afterwards".

But hey, what do I know?

Re: Grammar issue(s) in documentation

[Randy Dunlap]

On March 3, 2025 3:41:08 PM PST, Joshua Rose <joshuarose@gmx.com> wrote:
>Hi all,
>

>
>
>As an additional note, I'm looking for any recommendations on a good
>resource on the maintenance of the Documentation/ directory.
>

Hi,
Please elaborate on this. I don't understand.

Thanks.



~Randy

Re: Grammar issue(s) in documentation

[Jonathan Corbet]

Joshua Rose <joshuarose@gmx.com> writes:

> Hi all,
>
> I just wanted to briefly point out that as a native English speaker I
> found the following text significantly hard to read.
>
> "Do not worry installing your kernel manually and thus bypassing your
> distribution’s packaging system will totally mess up your machine: all
> parts of your kernel are easy to remove later, as files are stored in
> two places only and normally identifiable by the kernel’s release
> name."[1]
>
> I found this very hard to read. I would probably re-phrase this as
> follows, but I'd be completely open - and in fact encourage - any
> suggestions on the rephrasing of the excerpt.
>
> "Do not attempt to circumvent your distribution's packaging system by
> installing your kernel manually; this will likely break your machine.
> Components of your kernel can be selectively removed later on.  Such
> components (files) are stored in two locations, both identifiable
> by the kernel's release name."

I think you have completely reversed the meaning of that text - which
perhaps indicates that it is indeed in need of improvement :)

> As an additional note, I'm looking for any recommendations on a good
> resource on the maintenance of the Documentation/ directory.

Documentation/doc-guide/ would be the place to look. Do you have
specific questions?

Thanks,

jon

Re: Grammar issue(s) in documentation

[Joshua Rose]

On Tue, Mar 04, 2025 at 01:53:22AM +0000, Matthew Wilcox wrote:
> On Tue, Mar 04, 2025 at 10:41:08AM +1100, Joshua Rose wrote:

> > "Do not attempt to circumvent your distribution's packaging system by
> > installing your kernel manually; this will likely break your machine.
> > Components of your kernel can be selectively removed later on.  Such
> > components (files) are stored in two locations, both identifiable
> > by the kernel's release name."
>
> I think that's the opposite of what they meant.  I understand it as:
>
> "Feel free to circumvent your distribution's package manager as it's
> easy to remove the kernel afterwards".

Oh I see. Okay, well can it just be re-phrased as that then? It seems
much simpler.


Kind regards,
Joshua Rose

Re: Grammar issue(s) in documentation

[Thorsten Leemhuis]

On 05.03.25 01:48, Joshua Rose wrote:
> On Tue, Mar 04, 2025 at 01:53:22AM +0000, Matthew Wilcox wrote:
>> On Tue, Mar 04, 2025 at 10:41:08AM +1100, Joshua Rose wrote:
> 
>>> "Do not attempt to circumvent your distribution's packaging system by
>>> installing your kernel manually; this will likely break your machine.
>>> Components of your kernel can be selectively removed later on.  Such
>>> components (files) are stored in two locations, both identifiable
>>> by the kernel's release name."
>>
>> I think that's the opposite of what they meant.  I understand it as:
>>
>> "Feel free to circumvent your distribution's package manager as it's
>> easy to remove the kernel afterwards".

+1

> Oh I see. Okay, well can it just be re-phrased as that then? It seems
> much simpler.

Feel free to submit a patch yourself to adjust that, as yes, that
accidentally became a too long and confusing sentence white I wrote or
edited that text. But also feel free to leave sending a patch to me,
just give me a few days to handle that please. Ciao, Thorsten