On Tue, Apr 25, 2023 at 3:01 PM Nathan Hartman wrote: > On Tue, Apr 25, 2023 at 8:37 AM Tomek CEDRO wrote: > > 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.)
Thank you for clarification Nathan! I am also pro all-in-one place kind of documentation. git+sphinx seems more community friendly. So initial task is to migrate contents from cwiki to git+sphinx, then remove cwiki doc and use cwiki for some other tasks like roadmap etc? :-) > 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/"). Yes I like the idea, as we would have then all-in-one Handbook, and easy to follow src+doc structure :-) I can see that in current approach documentation is not part of the source code (i.e. no Doxygen like solutions). I guess there is no problem with organizing the Documentation/ part of the repo to resemble fully the source code structure, so commits would be easy to follow and verify (the code + doc part)..? > Right now, it is well acknowledged that our documentation is lacking in > several areas. Any help improving it will be tremendously appreciated. No worries, it all takes time and work, I am eager to help :-) > 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. :-) yeah! :-) > > 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 probably won't be any tremendous amount, but it could go into freelance hands that work on an important parts (i.e. Yup porting to PinePhone).. this could be somehow discussed/applied/voted before distribution. Just an idea on how to help project grow :-) Kivy for instance uses OpenCollective (https://kivy.org/#donate), If the ASF has this capabilities we could use ASF for sure :-) > This > > would be also probably the first point of contact with the project for > > the newcomers. > Agreed. :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
