On Tue, Apr 25, 2023 at 8:37 AM Tomek CEDRO <to...@cedro.info> wrote:
> Hello world :-) > > I was on a trip recently (and it happens quite often) so I was looking > for a PDF version of NuttX Documentation, kind of Handbook, but I did > not find one. > > I got used to PDF Handbook style because it is all-in-one approach > that is also easily available and searchable offline. > > As I am getting into details and reading the docs, so I can help this part > :-) > > I would like to know what is the current and past approach to the > documentation, to plan the work and align the tasks (with other people > working on the documentation?). What is the future preferred way of > documentation? git+documentation? (c)wiki? In the past, documentation was partly in README files in various directories in the repo, partly on the NuttX website which was running on MediaWiki. As the project moved to Apache Software Foundation, most of the MediaWiki was migrated into CWIKI (because ASF has that setup) and there has been a gradual effort to reorganize the content of the README files in the repo under the Documentation directory and convert them from purely text to Sphinx format (which is still text and readable in its source format, but can be processed into webpages and probably PDF; it would be nice to offer a download link to the latest generated PDF from the NuttX website). I think that some docs were copied and pasted from the CWIKI to the in-repo Documentation directory but I don't know whether everything was. Some important stuff might be missing. Personally I think it would be best to put all the docs in Documentation in the repo and _not_ continue to keep it in the CWIKI. (But first we should ensure everything has been migrated so that we won't lose anything.) In the past some people expressed that they wanted to centralize docs for boards under Documentation rather than keeping README files scattered around. I responded that if we do that, we should have a directory structure under Documentation that parallels the structure under boards, which will serve both to keep things organized and to make it easy, given a board path, to find its corresponding docs path (i.e., just prepend "Documentation/"). Right now, it is well acknowledged that our documentation is lacking in several areas. Any help improving it will be tremendously appreciated. Among other improvements, it would be nice if the documentation could be organized to flow like a NuttX Handbook. I totally recommend to look at the FreeBSD Handbook for inspiration. :-) I know there is a doc part on the website that is generated from the > main repository Documentation/ location. This part seems to need some > improvement (looks a bit like incomplete copy-paste?) :-) > > I know there is a CWIKI. I know there was some bigger documentation > before..? > > It would be best to have HTML and PDF documentation (maybe other > formats too) in a form of "Handbook" (all-in-one-place + searchable + > offline). This Handbook could be also provided in a form of e-book for > free and maybe some pay-as-you-want basis to support the project. Not sure how donations would work. Probably they would have to be paid directly to ASF, but I think it is possible to earmark donations for specific things or projects. This is something that needs to be checked. This > would be also probably the first point of contact with the project for > the newcomers. Agreed. As a reference documentation I could point to: > 1. https://docs.freebsd.org/en/books/handbook/ > 2. https://kivy.org/doc/stable/ > > Please let me know what you think folks :-) > Tomek > > -- > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info Cheers Nathan <http://www.tomek.cedro.info>
