Approachability of Documentation Generation

[Joel Sherrill]

Hi

The other thread has a mix of detailed "review this" versus philosophy on
how to make the documentation generation process approachable so Sebastian
isn't the only human capable of maintaining it. I want to talk at a high
level about making the process approachable. The major factor in the push
from texinfo to Sphinx was to increase the number of people who knew the
format markup language and tools. We are now moving in a direction where we
have a very unique system that we are responsible for making approachable.
Otherwise, we are stuck with a system even fewer people know than texinfo.

These are random thoughts about different ways to address this problem:

   - Do not generate the documentation
      - Although this is an option, I think we all agree that there is
      value to generating multiple artifacts from the same sources for
      consistency. This unfortunately puts the burden on us to avoid having the
      generation process
   - Clear way to identify generated sections
   - Clear way to trace generated sections to yaml file source
      - All sections of generated documentation could be "fenced" with
      "start generated from XXX" and "end generated from XXX".  The
XXX should be
      very specific.
      - Another approach which I don't think I like as much is to have a
      roadmap sister document which follows the outline and shows
where each part
      came from. This would have to be automatically generated to be accurate.
      This seems to just create burden and yet another document which a human
      would have to look at and correlate to figure out what they should edit.
   - Exception documentation on writing RtEMS documentation (tests,
   headers, etc) including extremely accurate and detailed information on the
   Yaml files.
      - This is mandatory. We are heading to a very project
      specific workflow and toolchain.
   - Chris' thought that in the case manually generated content  is added,
   we need a way to know and check that so it isn't lost.
      - Possible solution. Generation tool adds checksum and checks that
      generated file matches before replacing it.

I'm sure there are other challenges but this particular generation process
flies in the face of what drove many of the RTEMS process changes over the
past decade. We went from CVS to git, texinfo to Sphinx, and autoconf to
waf because we wanted to move to more modern tools that more people knew.
With texinfo, we also had our own texinfo to html converter and had to
switch to the official one before the Sphinx conversion to avoid owning a
tool not core to our mission. I believe this generation process is good for
the RTEMS mission but we need to be very cognizant of the impact this has.
How can we avoid mistakes in the workflow? How do we bring new users up to
speed?

The idea that very few people have contributed to our documentation is now
a good thing and unless we are very careful, the promise of Sphinx opening
that group up is not going to happen. Worse, it could easily shrink the set
of people who contribute to the documentation.

Thanks for doing this but it needs to be approachable to a high school
student. We need to remember that.

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