Call for Ideas and Content: Documenting Benefits of RTEMS Features

[Joel Sherrill]

Hi

The RTEMS documentation is very good at technical details but short on the
benefit of each feature. For example, the combination of per-symbol linking
and the current system initialization results in smaller code and less code
in the linked executable to audit. The details of those features are
covered but not the whys and benefits to systems design.

We tend to talk about the whats without the whys or benefits.

As a broad topic for thinking, are we missing the boat by not including
this in the manuals? What's the benefit of each scheduler, clustered
scheduler, the recent static task and message queues, sysinit, linking by
sections, our source code layout, configuration options, waf, all the
generation, etc., etc.

At a higher level, over the past few years, we have changed our view on
releases and what users do. I now speak of "RTEMS Project Source Releases"
and Chris added the term deployment for what users do. I use the term RTEMS
Distribution for packaging up tools for distribution whether inside one or
across organizations. The technical pieces are there for all this but we
don't do a good job of making this model known, the roles each plays, and
where we think handoffs occur.

We have a lot of good stuff in RTEMS and I would like to start a trend
where we add a "this is good to use in a system when ... because..." and
"this is beneficial when..." to the documentation.

Our documentation is now what people find via Google to see what's in
RTEMS. Adding the systems view will help draw them in because they will see
that we are thinking of applications, deployments, reproducibility,
validation, analysis, stability, and long-term maintenance.

That's the challenge I put to the community. Let's add bits to the
documentation to explain why something is useful in an application, helps
with validation, schedulability analysis, etc.. Let's bring the systems
view into our documentation.

--joel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20201009/56dc4c85/attachment.html>