David.
>
> Sarah
>
> On Tue, Apr 12, 2016 at 11:06 AM, Bert Gunter <bgunter.4567 at gmail.com> wrote:
>> FWIW:
>>
>> 1. I agree that this is an idea worth considering. Especially now that
>> R has become so widely used among practitioners who are neither
>> especially software literate nor interested in poring over R manuals
>> (as I did when I first learned R). They have explicit tasks to do and
>> just want to get to them as directly as possible.
>>
>> 2. A partial reply to the (fair) criticism of those who criticize docs
>> without offering improvements is that one may not know what
>> improvement to offer precisely because the docs do not make it clear.
>> This proposal or something similar addresses this issue. The experts
>> could adjudicate.
>>
>> 3. I agree: writing good docs is hard. Having a mechanism like this
>> would also help non-native English writers of software (or challenged
>> native writers like me!) .
>>
>> 4. I also think John is right, that if the right mechanism were found
>> so that small efforts could be accumulated, a lot of us would
>> participate. A wiki sounds about right, but I bow to those with
>> greater wisdom and experience here.
>>
>> 5. The danger here is that this would suck a lot of time from R core.
>> That's unacceptable. Presumably a wiki (self-correcting?) would help
>> avoid this.
>>
>> Cheers,
>> Bert
>> Bert Gunter
>>
>> "The trouble with having an open mind is that people keep coming along
>> and sticking things into it."
>> -- Opus (aka Berkeley Breathed in his "Bloom County" comic strip )
>>
>>
>> On Tue, Apr 12, 2016 at 6:21 AM, ProfJCNash <profjcnash at gmail.com> wrote:
>>>
>>>>>>> "The documentation aims to be accurate, not necessarily clear."
>>>> I notice that none of the critics
>>>> in this thread have offered improvements on what is there.
>>>
>>>
>>> This issue is as old as documented things. With software it is
>>> particularly nasty, especially when we want the software to function
>>> across many platforms.
>>>
>>> Duncan has pointed out that critics need to step up to do something.
>>> I would put documentation failures at the top of my list of
>>> time-wasters, and have been bitten by some particularly weak offerings
>>> (not in R) in the last 2 weeks. So ....
>>>
>>> Proposal: That the R community consider establishing a "test and
>>> document" group to parallel R-core to focus on the documentation.
>>> An experiment to test the waters is suggested below.
>>>
>>> The needs:
>>> - tools that let the difficulties with documentation be visualized along
>>> with proposed changes and the discussion accessed by the wider
>>> community, while keeping a well-defined process for committing accepted
>>> changes.
>>> - a process for the above. Right now a lot happens by discussion in the
>>> lists and someone in R-core committing the result. If it is
>>> well-organized, it is not well-understood by the wider R user community.
>>> - tools for managing and providing access to tests
>>>
>>> At the risk of opening another can of worms, documentation is an area
>>> where such an effort could benefit from paid help. It's an area where
>>> there's low reward for high effort, particularly for volunteers.
>>> Moreover, like many volunteers, I'm happy to do some work, but I need
>>> ways to contribute in small bites (bytes?), and it is difficult to find
>>> suitable tasks to take on.
>>>
>>> Is it worth an experiment to customize something like Dokuwiki (which I
>>> believe was the platform for the apparently defunct R wiki) to allow a
>>> segment of R documentation to be reviewed, discussed and changes
>>> proposed? It could show how we might get to a better process for
>>> managing R documentation.
>>>
>>> Cheers, JN
>>>
> --
> Sarah Goslee
> http://www.functionaldiversity.org
>
> ______________________________________________
> R-help at r-project.org mailing list -- To UNSUBSCRIBE and more, see
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
David Winsemius
Alameda, CA, USA