R help - May 2009 - R's documentation

Sometimes I get confused with R's documentation. It seems the documents is
not maintained and updated well. Anyone has similar feeling? I don't mean to
offend anyone. I hope R would get better and better. But documentation is really
one very important factor which could attract people coming or drive people
away.

Xin Zheng


	[[alternative HTML version deleted]]

On Fri, May 29, 2009 at 11:01 AM, Zheng, Xin (NIH) [C] <
zhengxin@mail.nih.gov> wrote:
> Sometimes I get confused with R's documentation. It seems the documents
is
> not maintained and updated well. Anyone has similar feeling? I don't
mean to
> offend anyone. I hope R would get better and better. But documentation is
> really one very important factor which could attract people coming or drive
> people away.

¿Do you have any specific example? Without examples it is difficult to say
much.
¿Do you refer to the core part of R, or to contributed packages?

My impression is that when some functions are changed, the documentation is
generally
changed at the same time. And I am sure that is the goal, so if you know a
case where it did not happen you should
file a bug report.

kjetil

>
>
> Xin Zheng
>
>
>        [[alternative HTML version deleted]]
>
> ______________________________________________
> R-help@r-project.org mailing list
> 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.
>
	[[alternative HTML version deleted]]

Zheng, Xin (NIH) [C] wrote:
> Sometimes I get confused with R's documentation. It seems the documents
is not maintained and updated well. Anyone has similar feeling? I don't mean
to offend anyone. I hope R would get better and better. But documentation is
really one very important factor which could attract people coming or drive
people away.
>
> Xin Zheng
>   
Please be specific about __how__ you are confused by __which__ documents 
and I am convinced you will get sarcasm-free replies.

Romain

-- 
Romain Francois
Independent R Consultant
+33(0) 6 28 91 30 30
http://romainfrancois.blog.free.fr

Zheng, Xin (NIH) [C] wrote:
> Sometimes I get confused with R's documentation. It seems the
> documents is not maintained and updated well. Anyone has similar
> feeling? I don't mean to offend anyone. I hope R would get better and
> better. But documentation is really one very important factor which
> could attract people coming or drive people away.
> 
I absolutely agree.

This is an area where novices as well
as seasoned R users can give to the R
project.

If you find some documentation that is
confusing, then you can write a message
about it that states:

1) Precisely what you find confusing.

2) (optional but very helpful) A
proposed rewrite of the passage that
you think fixes the problem.


Once you attempt step 2 a few times, you
may come to appreciate the difficulty of
writing good documentation.

Help files are a particularly difficult
medium -- they need to be clear (to novices,
not just to the person who wrote the function),
and they need to be short enough that people
might read them.


Patrick Burns
patrick at burns-stat.com
+44 (0)20 8525 0696
http://www.burns-stat.com
(home of "The R Inferno" and "A Guide for the Unwilling S
User")

> Xin Zheng
> 
> 
> [[alternative HTML version deleted]]
> 
> ______________________________________________ R-help at r-project.org
> mailing list 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.
>

On Fri, May 29, 2009 at 11:01 AM, Zheng, Xin (NIH) [C]
<zhengxin at mail.nih.gov> wrote:
> Sometimes I get confused with R's documentation. It seems the documents
is not maintained and updated well. Anyone has similar feeling? I don't mean
to offend anyone. I hope R would get better and better. But documentation is
really one very important factor which could attract people coming or drive
people away.
>
The svn log shows when each file was updated and its pretty
clear that they are constantly being updated.
http://developer.r-project.org/R.svnlog.2009

There are third party introductions and many books available.