On Tue, Apr 25, 2023 at 7:26 PM Brennan Ashton wrote: > On Tue, Apr 25, 2023, 6:10 PM Tomek CEDRO wrote: > (..) > > After some consideration a "safer" approach may be more desirable for now: > > > > 1. Migrate all documentation to a separate Documentation/ as it is > > currently done, so we do not lose any content from > > MediaWiki/README/CWIKI, we can add additional content that we need, > > the documentation form is shaped to a satisfactory state, automation > > is verified, nice references, tables of contents, sections, etc. > > People will have solid documentation all the time and we cause no mess > > and we can see how the work on doc goes in reality :-) > > > > 2. When we have a well shaped "separate" documentation then it may be > > the time to consider merging it with the source code, but not before, > > if desired at all? > > > > What do you think? > > Eh I don't think we should pull the docs apart. Its a pain to manage > especially with sphinx if we start sprinkling the docs all over the place. > it's also hard in my opinion to write clear cohesive docs thare do not get > highly repetitive if each section lives in isolation. This unified style > is also what we seen in projects like Zephr and Linux > https://github.com/torvalds/linux/tree/master/Documentation > https://github.com/zephyrproject-rtos/zephyr/tree/main/doc > > All this said, there is no reason to not also write clear comments in the > code, especially code that may be incomplete, complex, hiding dragons or > otherwise confusing.
Roger! So the doc stays separated from the src :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
