On 4/25/2023 11:38 AM, Nathan Hartman wrote:
> I like the idea of keeping documentation in sync with the code(as much as
> possible given our volunteer-based project).
I wouldn't make a plan that depends on that. Engineers are notoriously
bad at maintaining documentation. And international projects like this
one also have language issues.
I presume that English is the language for NuttX documentation? In the
past we did have partial ports of the DocuWiki to Portuguese and
Turkish, but I think English has been the primary language.
The majority of NuttX contributors may not be fluent in English. They
may speak only their native language or may have limitations in their
English skills. You can see this in the complete absence of comments in
sections of code.
So (1) you can never be assured that code is even close to
self-documenting and (2) you have to assume the burden of any
documentation effort will fall on the native English speakers and those
with very good English-as-a-second-language skills.
> Regarding the CWIKI, suppose we want to document something in particular.
> The CWIKI can be a good place for several people to put it together with
> realtime collaboration without having to deal with GitHub PRs and
whatever,
> and when it gets close to ready, it can be migrated into Documentation.
> This is what we've been doing with the Release Notes and it seems to work
> well.
AFAIK no one contributes to the CWIKI. I have always wanted to have
community-based documentation development like you could get with a
Wiki. There were several contributors to the old DocuWiki but I would
not consider it successful in this regard either.
As I recall, it is not a simple matter for a non-committer in the
community to get access to Confluence in order to modify the Wiki. Is
that correct?
Tomasz Cedro now owns nuttx.com and nuttx.org. One use of nuttx.org
might be to use it to provide such a open, collaborative Wiki. A
gitbook might be better option. Apparently Brennan Ashton created on
https://cwiki.apache.org/confluence/display/NUTTX/Nuttxbook but the
links there all get 404 error.
