On Tue, Apr 25, 2023, 7:14 PM Gregory Nutt <spudan...@gmail.com> wrote:
> 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? > You have to make an Apache account now because the amount of spam the wiki was seeing was too high. Unless we want to get in the moderation business I expect to see a lot of that on any wiki these days (I even had to turn off comments on my captcha protected blog no one reads....). If anyone does have something they want to add to the wiki that we are not porting to the repo I'm happy to help get them setup. It has been useful as mentioned for adhoc things like getting the release notes together. --Brennan >
