Fwd: Documentation on IMA for Linux Kernel Documentation

Fwd: Documentation on IMA for Linux Kernel Documentation

[Ken Goldman]

I'm writing documentation on IMA targeting users (not kernel 
developers).  It includes concepts, details on writing policies, the IMA 
event log format, utilities, and more.  It aggregates existing scattered 
documentation, but adds much more.  It's maybe 1/2 done.

Questions:

1. Are there people who could look at it and see if I'm on the right path?

It's a lot of work.  I'd like to know that it has some chance of acceptance.

2. What is the process for getting a block of documentation added to 
https://www.kernel.org/doc/html?

Re: Documentation on IMA for Linux Kernel Documentation

[Randy Dunlap]

Hi Ken,

On 3/22/23 15:02, Ken Goldman wrote:
> On 3/13/2023 6:34 PM, Randy Dunlap wrote:
>> On 3/13/23 15:25, Randy Dunlap wrote:
>>> [add IMA list]
>>>
>>> On 3/13/23 14:43, Ken Goldman wrote:
>>>> I'm writing documentation on IMA targeting users (not kernel developers).  It includes concepts, details on writing policies, the IMA event log format, utilities, and more.  It aggregates existing scattered documentation, but adds much more.  It's maybe 1/2 done.
>>>>
>>>> Questions:
>>>>
>>>> 1. Are there people who could look at it and see if I'm on the right path?
>>>>
>>>> It's a lot of work.  I'd like to know that it has some chance of acceptance.
>>>>
>>>> 2. What is the process for getting a block of documentation added to https://www.kernel.org/doc/html?
>>>
>>> It should be added to the kernel tree in the Documentation/userspace-api/ subdirectory
>>> or Documentation/security/ subdirectory.  The kernel.org/doc/ web pages are generated
>>> from what is in the Linux kernel tree.
>> Ken, if you are not familiar with in-tree kernel documentation, you should take a look
>> at the Documentation/doc-guide/ subdirectory for some documentation on the documentation.
>>
>> Also you can ask for help with specific issues at linux-doc@vger.kernel.org
> 
> I've read the guidelines, coding in rest markdown, using sphinx to test the web pages.  I think it's right.
> 
> 1. I was hoping that someone could look at what I'm doing to see if it has a chance of acceptance.
> 
> I.e., I don't want to spend months on this only to get a quick 'nack'.
> 
> 2. I wonder what the process for submission is.

It's documented in Documentation/process/submitting-patches.rst,
but just ask if you have any questions about it.

-- 
~Randy

Re: Fwd: Documentation on IMA for Linux Kernel Documentation

[Randy Dunlap]

On 3/22/23 15:04, Ken Goldman wrote:
> I'm writing documentation on IMA targeting users (not kernel developers).  It includes concepts, details on writing policies, the IMA event log format, utilities, and more.  It aggregates existing scattered documentation, but adds much more.  It's maybe 1/2 done.
> 
> Questions:
> 
> 1. Are there people who could look at it and see if I'm on the right path?
> 
> It's a lot of work.  I'd like to know that it has some chance of acceptance.

Review in terms of IMA-specific content?  or in terms of ReST usage?
or in general terms to see if it is appropriate for kernel tree documentation?

I think that you should Cc: linux-integrity@vger.kernel.org for their input
as well as linux-doc@vger.kernel.org. Several of us here can look at it for
general review feedback.

> 2. What is the process for getting a block of documentation added to https://www.kernel.org/doc/html?

From last week's email:

>>> It should be added to the kernel tree in the Documentation/userspace-api/ subdirectory
>>> or Documentation/security/ subdirectory.  The kernel.org/doc/ web pages are generated
>>> from what is in the Linux kernel tree.

although if you don't think that it is appropriate for either of those subdirectories,
just explain and justify that and it might be possible to put it somewhere else.

-- 
~Randy

Re: Fwd: Documentation on IMA for Linux Kernel Documentation

[Ken Goldman]

On 3/22/2023 6:58 PM, Randy Dunlap wrote:
> On 3/22/23 15:04, Ken Goldman wrote:
>> I'm writing documentation on IMA targeting users (not kernel developers).  It includes concepts, details on writing policies, the IMA event log format, utilities, and more.  It aggregates existing scattered documentation, but adds much more.  It's maybe 1/2 done.
>>
>> Questions:
>>
>> 1. Are there people who could look at it and see if I'm on the right path?
>>
>> It's a lot of work.  I'd like to know that it has some chance of acceptance.
> Review in terms of IMA-specific content?  or in terms of ReST usage?
> or in general terms to see if it is appropriate for kernel tree documentation?
>
> I think that you should Cc: linux-integrity@vger.kernel.org for their input
> as well as linux-doc@vger.kernel.org. Several of us here can look at it for
> general review feedback.

Not the accuracy - I have IMA experts looking at that.

I want to know if it'll be accepted, and if the structure is OK.

> 2. What is the process for getting a block of documentation added to 
> https://www.kernel.org/doc/html?
>  From last week's email:
>
>>>> It should be added to the kernel tree in the Documentation/userspace-api/ subdirectory
>>>> or Documentation/security/ subdirectory.  The kernel.org/doc/ web pages are generated
>>>> from what is in the Linux kernel tree.
> although if you don't think that it is appropriate for either of those subdirectories,
> just explain and justify that and it might be possible to put it somewhere else.

"Where" comes later.  I just want to know if it'll be accepted at all.

Re: Fwd: Documentation on IMA for Linux Kernel Documentation

[Jonathan Corbet]

Ken Goldman <kgold@linux.ibm.com> writes:

> On 3/22/2023 6:58 PM, Randy Dunlap wrote:
>> Review in terms of IMA-specific content?  or in terms of ReST usage?
>> or in general terms to see if it is appropriate for kernel tree documentation?
>>
>> I think that you should Cc: linux-integrity@vger.kernel.org for their input
>> as well as linux-doc@vger.kernel.org. Several of us here can look at it for
>> general review feedback.
>
> Not the accuracy - I have IMA experts looking at that.

You still want to copy the integrity list for something like this; they
will have the ultimate say on whether it makes sense for inclusion into
the kernel tree.

> I want to know if it'll be accepted, and if the structure is OK.

...and that's hard to answer without seeing the work.  It's better to
just post what you have then to ask whether you should.

>> 2. What is the process for getting a block of documentation added to 
>> https://www.kernel.org/doc/html?
>>  From last week's email:
>>
>>>>> It should be added to the kernel tree in the Documentation/userspace-api/ subdirectory
>>>>> or Documentation/security/ subdirectory.  The kernel.org/doc/ web pages are generated
>>>>> from what is in the Linux kernel tree.
>> although if you don't think that it is appropriate for either of those subdirectories,
>> just explain and justify that and it might be possible to put it somewhere else.
>
> "Where" comes later.  I just want to know if it'll be accepted at all.

We're not in the habit of turning down good documentation.  Please, post
your work to the relevant lists and we'll go from there.

Thanks,

jon