[R] Improving help in R

[Patrick Connolly]

On Wed, 14-Mar-2012 at 11:39PM +0100, Tomáš Křehlík wrote:

|> Hello R people
|> 

[...]

|> The best documentation that I ever used is probably one of
|> Mathematica, look for example here
|> http://reference.wolfram.com/mathematica/ref/Fit.html (it is
|> somehow related to the stuff below).


[...]


|> What I would like to receive from you is your opinions about this
|> topic. The stuff that I did is pretty easy to do even
|> algorithmically (some parser could probably parse the existing help
|> files). The only added value here is making important stuff more
|> visible. I also added the "dummies" example.

In my experience, pretty fonts are no benefit over what we have.  This
is a case of "less is more".  I particularly dislike that use of
dropcaps.  I think of function names in a case-sensitive way and
seeing capitals, even 'dropped', just doesn't convey lower case.
There is a place for dropcaps -- maybe for the headings "Examples",
"Usage", etc., but not for function names.

I'm also very keen on fonts.  For me, by far the most useful way to
represent the precise keys that are typed, a monospaced font is the
most easily read.  It's a convention used in pretty well every text
book I've read and I think there's a good reason for that.  The
examples you give I find relatively difficult to read because the font
is proportional spaced.

I read help files in an Emacs buffer which I can search and traverse
with very few keystrokes and have become very familiar with the
headings that are used.  My primary interest is the syntax and then if
the parameter name isn't obvious from the context, that's the next
thing I want described.  If it's not obvious to me how the function
works, I can run the examples line by line with a single key-stroke
for each line.  There's nothing I know of that can hold a candle to
that approach.


|> So please tell me what you think. I am a bit busy and if I do
|> anything with it I would like to have it thought through carefully
|> beforehand. Also if anybody would be interested in helping, or if
|> he is running similar project, tell me.

Apologies for coming across so negative, but it is what I think.
People who hadn't used a computer before the days of Windows XP will
possibly think of it rather differently, but for me, it's a case of
"If it ain't broke, don't fix it."  There might be ways of improving
the help files, but I think they're already very well-thought out
(even if that doesn't apply to every package).


HTH


-- 
~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.   
   ___    Patrick Connolly   
 {~._.~}                   Great minds discuss ideas    
 _( Y )_  	         Average minds discuss events 
(:_~*~_:)                  Small minds discuss people  
 (_)-(_)  	                      ..... Eleanor Roosevelt
	  
~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.