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>

Reply via email to