Re: [PATCH 6/8] Documentation: Create a new folder for all timer internals

[Anna-Maria Behnsen]

Randy Dunlap <rdunlap@xxxxxxxxxxxxx> writes:

> Hi,
>
> On 1/23/24 08:47, Anna-Maria Behnsen wrote:
>> The structure of documentation changed. There is 'core-api' where also
>> timer related documentation belongs to. But the timer related documentation
>> (doesn't matter whether it is up to date or outdated) is still located in a
>> separate folder with no relation to core-api.
>> 
>> Create a new folder which is located below core-api and make it the new
>> place for all timer related documentation. Instead of revisiting all files
>> below the already existing timer folder right now, add a warning banner to
>> the top of all those files. When it is ensured the content is up to date,
>> they can be moved to the final destination.
>> 
>> Signed-off-by: Anna-Maria Behnsen <anna-maria@xxxxxxxxxxxxx>
>> ---
>>  Documentation/core-api/index.rst        |  1 +
>>  Documentation/core-api/timers/index.rst | 22 ++++++++++++++++++++++
>>  Documentation/timers/highres.rst        |  5 +++++
>>  Documentation/timers/hpet.rst           |  5 +++++
>>  Documentation/timers/hrtimers.rst       |  5 +++++
>>  Documentation/timers/index.rst          |  5 +++++
>>  Documentation/timers/no_hz.rst          |  4 ++++
>>  Documentation/timers/timekeeping.rst    |  5 +++++
>>  Documentation/timers/timers-howto.rst   |  5 +++++
>
> When can we remove the old, "might be outdated" files?
> Do you think that some of their contents might be valuable to someone?
>
> I prefer not to have the old documentation and the new.
>

This is also nothing I prefere for a final solution. But I got stucked
when I was looking for a way to add the actual documentation because I
wanted to add it into a cleaned-up environment. But I don't have the
possibility at the moment to cleanup the existing timer documentation
right away with all its aspects (content, formatting, referencing,
location below Documentation,... ).

So I had those options:

1. wait until I have time for all this before publishing the new
   documentation -> not an option because I don't know when there is
   time to do all those things in one go

2. Put the new documentation below the existing one and ignore the rest
   silently (maybe someone else will clean it up someday) -> not an
   option because it suggests that the new documentation structure is
   just ignored

3. Just move the old documentation without revisiting it -> not an
   option because there might be outdated information and then it
   doesn't has a benefit for the reader

4. Add a warning banner at the existing documentation and prepare
   everything to get the timer documentation to the proper place and
   create a place for timer documentation below the current structure.

The benefit of 4. for me is, that there is this warning banner at the
top. So this suggests the reader, that this has to be revisited before
relying on it for 100%. This banner might also remind the original
author/technically deep involved developer that this should be
updated.

If there is a better way to go, please let me know!

Thanks,

        Anna-Maria