Quantcast

Improving help in R

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Improving help in R

tomas.krehlik
Hello R people

I always wander what other people say about the R help. Finally after some years of using, I decided that it is probably time to try to do something about it, because the feeling of gritting teeth does not go away with years of usage. :) Moreover, I think it is one of the few things where R does not kick asses to the other statistical softwares. So, to the point:

I get the feeling (by some experience with learning programming languages when I am not primarily a programmer but economist/statistician) that structure of help really helps and I would like to have it to go in the way

basic syntax (by basic I really mean only the necessary arguments)
example for "dummies", to see what it does
click-here-if-you-want-to-know-more menu/button
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).

So what I did is that I took R help file for Fitting Linear Models ( http://stat.ethz.ch/R-manual/R-patched/library/stats/html/lm.html ) and put it into some more readable shape for me. So I built some other version (actually two) look at http://pinda.sifruje.cz/ . The "original" is just the same text taken and only some basic stuff solved (on my 27 inch monitor, if I make the browser full screen the original help is almost unreadable, because it stretches from one end to the other. Next we already have some pretty good fonts so why not to use them, here Linux Biolinum, and I did some to me aesthetic changes...). The "custom" goes a bit deeper and tries to implement a bit more of my thoughts. The buttons are really made quickly and only as an example. Also I do not claim that the code is anywhere good, I spent like hour or two just sawing some pieces that already lay around web. Just take it as some demonstration.

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.

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.

Thanks, Tomas.
        [[alternative HTML version deleted]]

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Improving help in R

Patrick Connolly-4
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
         
~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Improving help in R

Barry Rowlingson
In reply to this post by tomas.krehlik
2012/3/14 Tomáš Křehlík <[hidden email]>:
> Hello R people

> I get the feeling (by some experience with learning programming languages when I am not primarily a programmer but economist/statistician) that structure of help really helps and I would like to have it to go in the way
>
> basic syntax (by basic I really mean only the necessary arguments)

type 'args(lm)'

> example for "dummies", to see what it does

type 'example(lm)', or 'example(lm,give.lines=TRUE)' if you want to
see the example and not run it.

> click-here-if-you-want-to-know-more menu/button

 type '?lm'

 I don't think I've ever used the html help system in R, except to go
'ooh, there's an HTML help system'.

> 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.
>
> 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.

I jush had a look at a couple of html help pages for the first time in
ages, and yes they could possibly benefit from some restyling, but you
have to remember that these are generated from text .Rd files, and
also need to be able to be rendered into plain text for us ESS-using
dinosaurs. I think I would first rewrite the Rd to HTML converter to
make the HTML more semantic, then use CSS to style it better - perhaps
the various sections could go into tabs or an accordion-style UI
component.

Of course the real way to do this is to do some user experience
research. I mostly use the help to remember argument names and
ordering, which I can actually do by typing foo( and hitting TAB
(twice in the command line).

But certainly the lines are waaay too long on a decent sized monitor.
Which is why an 80-column ESS window is winning! :)

Barry

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Improving help in R

Berend Hasselman
In reply to this post by tomas.krehlik

On 14-03-2012, at 23:39, Tomáš Křehlík wrote:

> Hello R people
>
> I always wander what other people say about the R help. Finally after some years of using, I decided that it is probably time to try to do something about it, because the feeling of gritting teeth does not go away with years of usage. :) Moreover, I think it is one of the few things where R does not kick asses to the other statistical softwares. So, to the point:
>
> I get the feeling (by some experience with learning programming languages when I am not primarily a programmer but economist/statistician) that structure of help really helps and I would like to have it to go in the way
>
> basic syntax (by basic I really mean only the necessary arguments)
> example for "dummies", to see what it does
> click-here-if-you-want-to-know-more menu/button
> 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).
>

Opinions differ.
I think the example is too busy.

> So what I did is that I took R help file for Fitting Linear Models ( http://stat.ethz.ch/R-manual/R-patched/library/stats/html/lm.html ) and put it into some more readable shape for me. So I built some other version (actually two) look at http://pinda.sifruje.cz/ . The "original" is just the same text taken and only some basic stuff solved (on my 27 inch monitor, if I make the browser full screen the original help is almost unreadable, because it stretches from one end to the other. Next we already have some pretty good fonts so why not to use them, here Linux Biolinum, and I did some to me aesthetic changes...). The "custom" goes a bit deeper and tries to implement a bit more of my thoughts. The buttons are really made quickly and only as an example. Also I do not claim that the code is anywhere good, I spent like hour or two just sawing some pieces that already lay around web. Just take it as some demonstration.
>
> 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.

To be honest, I don't like your proposal at all.
For one, to see more in your custom version I have to click. And click again and often to see details that matter.
Please, give it all without forcing the viewer to click.

Second, some of the fontsizes are much too small (both in the original and custom version).
And they vary too much in size across the page.
On a Macbook Air 11inch the smaller fonts are totally unreadable.
Increasing browser fontsize leads to an unbalanced and rather ugly page.
And line width does not adjust so you have to scroll horizontally.

I would not want to use help pages in this format and layout.
My apologies for being negative. but this is how I feel about your proposal.

As far as I am concerned there are only two things that could be improved in the R help pages:
1. set a maximum line width (relative to windowsize)
2. use bold and/or some colour for headings.

Both of these issues could be tackled in the .css file.
Main point a for me would be: keep it functional and simple.

Berend

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Improving help in R

Duncan Murdoch-2
In reply to this post by tomas.krehlik
On 12-03-14 6:39 PM, Tomáš Křehlík wrote:

> Hello R people
>
> I always wander what other people say about the R help. Finally after some years of using, I decided that it is probably time to try to do something about it, because the feeling of gritting teeth does not go away with years of usage. :) Moreover, I think it is one of the few things where R does not kick asses to the other statistical softwares. So, to the point:
>
> I get the feeling (by some experience with learning programming languages when I am not primarily a programmer but economist/statistician) that structure of help really helps and I would like to have it to go in the way
>
> basic syntax (by basic I really mean only the necessary arguments)
> example for "dummies", to see what it does
> click-here-if-you-want-to-know-more menu/button
> 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).
>
> So what I did is that I took R help file for Fitting Linear Models ( http://stat.ethz.ch/R-manual/R-patched/library/stats/html/lm.html ) and put it into some more readable shape for me. So I built some other version (actually two) look at http://pinda.sifruje.cz/ . The "original" is just the same text taken and only some basic stuff solved (on my 27 inch monitor, if I make the browser full screen the original help is almost unreadable, because it stretches from one end to the other. Next we already have some pretty good fonts so why not to use them, here Linux Biolinum, and I did some to me aesthetic changes...). The "custom" goes a bit deeper and tries to implement a bit more of my thoughts. The buttons are really made quickly and only as an example. Also I do not claim that the code is anywhere good, I spent like hour or two just sawing some pieces that already lay around web. Just take it as some demonstration.
>
> 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.
>
> 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.

One difficulty in getting the help pages to look beautiful is that the
original input is so inconsistent, and package authors (naturally) get
upset when CRAN starts rejecting packages because of errors that used to
be ignored.  The current output is definitely a compromise aimed at
making most packages work.

However, this doesn't stop us from using a different style sheet. It
would be very easy to have the system generate pages with markup that
allowed a user to customize fonts, colours, etc.  The main difficulty
here is that R users use lots of different systems and lots of different
browsers, so it takes some work to find displays that work everywhere.
(For example, someone mentioned drop caps in your display, but I don't
see those in Firefox on Windows -- presumably I don't have the font you
specified.)

BTW, when you say "some parser could probably parse the existing help
files", it sounds as though you are unaware of the fact that the help
source is in Rd format, and it is parsed into various output formats.
You can see the parser in tools::parse_Rd, and the formatter in
tools::Rd2HTML.

If you want to continue to work on this, I'd be happy to continue the
discussion on R-devel.

Duncan Murdoch

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Improving help in R

Hadley Wickham-2
> One difficulty in getting the help pages to look beautiful is that the
> original input is so inconsistent, and package authors (naturally) get upset
> when CRAN starts rejecting packages because of errors that used to be
> ignored.  The current output is definitely a compromise aimed at making most
> packages work.
>
> However, this doesn't stop us from using a different style sheet. It would
> be very easy to have the system generate pages with markup that allowed a
> user to customize fonts, colours, etc.  The main difficulty here is that R
> users use lots of different systems and lots of different browsers, so it
> takes some work to find displays that work everywhere. (For example, someone
> mentioned drop caps in your display, but I don't see those in Firefox on
> Windows -- presumably I don't have the font you specified.)
>
> BTW, when you say "some parser could probably parse the existing help
> files", it sounds as though you are unaware of the fact that the help source
> is in Rd format, and it is parsed into various output formats. You can see
> the parser in tools::parse_Rd, and the formatter in tools::Rd2HTML.

And the great thing about those tools is that it's fairly easy to
convert Rd files into alternative help files. I've recently been
working on staticdocs (https://github.com/hadley/staticdocs) which
aims to convert Rd files into html particularly well suited for
distribution on standalone websites.  You can see the what the output
looks when applied to the ggplot2 package at
http://had.co.nz/ggplot2/docs/.

It's made possible by:

* Duncan's Rd parser
* twitter's bootstrap framework for html/css
* Romain Francois' highlight package (for syntax highlighting R code)
* Edwin de Jonge's whisker (for html templates)
* Barrett Schloerke's helpr package (which provided most of the initial code)

Hadley

--
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/

______________________________________________
[hidden email] 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.
Loading...