<div dir="ltr">Hi<div><br><div>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.</div><div><br></div><div>These are random thoughts about different ways to address this problem:</div><div><ul><li>Do not generate the documentation</li><ul><li>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 </li></ul><li>Clear way to identify generated sections</li><li>Clear way to trace generated sections to yaml file source</li><ul><li>All sections of generated documentation could be "fenced" with "start generated from XXX" and "end generated from XXX".  The XXX should be very specific.</li><li>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.</li></ul><li>Exception documentation on writing RtEMS documentation (tests, headers, etc) including extremely accurate and detailed information on the Yaml files. </li><ul><li>This is mandatory. We are heading to a very project specific workflow and toolchain.</li></ul><li>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. </li><ul><li>Possible solution. Generation tool adds checksum and checks that generated file matches before replacing it.</li></ul></ul>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?</div></div><div><br></div><div>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.</div><div><br></div><div>Thanks for doing this but it needs to be approachable to a high school student. We need to remember that.</div><div><br></div><div>--joel</div></div>