Re: [PATCH 3/3] Documentation: Add real-time

[Jonathan Corbet <corbet@lwn.net>]

Sebastian Andrzej Siewior <bigeasy@linutronix.de> writes:

> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>  Documentation/index.rst                 |   1 +
>  Documentation/real-time/differences.rst | 244 ++++++++++++++++++++++++
>  Documentation/real-time/index.rst       |  18 ++
>  Documentation/real-time/theory.rst      | 119 ++++++++++++
>  4 files changed, 382 insertions(+)
>  create mode 100644 Documentation/real-time/differences.rst
>  create mode 100644 Documentation/real-time/index.rst
>  create mode 100644 Documentation/real-time/theory.rst

So overall it looks good, but I do have one overriding question:

- Who is the audience for this documentation?

I think it's an important question to ask, because something this easily
becomes an unorganized pile of stuff that somebody thought should be
written down somewhere - better than nothing, but hard for readers to
use effectively.

A good first step would be to supply a paragraph or two in the new
Documentation/real-time/index.rst describing the nature of the
documentation and who it is intended for.

Then ... think about whether a new top-level directory under
Documentation makes sense.  I've been working for years to reduce those,
so I tend to push back a little when new ones show up.

- Is this documentation for kernel developers in general, with the idea
  of maybe helping them to not break PREEMPT_RT so often?  Then perhaps
  documentation with that focus under core-api/ makes sense.

- Is it, instead, intended as overall design documentation?  We don't
  really have a good place for that now, maybe we need a new design/
  book to gather such material.

See what I'm getting at?  I'm not saying that these docs *have* to go
somewhere else, but I do think it's worth thinking about.

Thanks,

jon