-
Notifications
You must be signed in to change notification settings - Fork 2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Many small vignettes #3
Comments
That's a great idea. We'll put it on the todo list. |
This could be accomplished by simply creating vignettes from the existing
man page examples.. perhaps via script?
…On Tue, Mar 3, 2020 at 9:16 AM Steffen Möller ***@***.***> wrote:
Search engines find the PDFs from CRAN. Having all of gplots covered with
a short example how the function/plot may be used, should be of
considerable help for newcomers.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#3?email_source=notifications&email_token=ABO4GX6DWBHXQGLDQZST3BLRFUGLLA5CNFSM4LALOIV2YY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4ISBGZ5Q>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABO4GX3EBV4KXKHDAKP4FUTRFUGLLANCNFSM4LALOIVQ>
.
--
"Whereas true religion and good morals are the only solid foundations of
public liberty and happiness . . . it is hereby earnestly recommended to
the several States to take the most effectual measures for the
encouragement thereof." Continental Congress, 1778
|
I am not sure. The script may be more work than the vignette and I presume that whoever starts writing the vignette is also likely to get ideas on how to improve the man page. A script would have the advantage to give it all some consistency - maybe we should just start with a few and then see if we can somehow find some common motifs in these vignettes. It may be helpful to start with a motivation for each diagram, which may not be part of what the man page provides. That motivation would then offer phrases that are likely to match search queries, like - "For comparing observations that share many numerical attributes, a heatmap may be the method of choice. There is no rule of thumb to the limits of observations or attributes since observations and attributes can be reordered and the human interpreter thus has the opportunity to compare aggregations (visual "blocks") instead of individual lines or columns. Over the default heatmap, this reimplementation grants extra freedom for .... ". If something like this is what we are aiming at then this does not fit the more vendor-neutral man pages. Google once discussed a GSoC for documentation writing. Sounds like a nice fit. Also we could have this for the Google Code-in. |
I'm thinking that the initial work should be as simple and easy as
possible, so we can maximize the initial benefit.
Perhaps we can use something like the Rd2md package
<https://cran.r-project.org/web/packages/Rd2md/> to convert the existing
man pages to Rmd files, then edit these to put the examples in code blocks
so they get executed.
It's a lot easier to revise an existing document, than to start from
scratch 😉.
I would be happy to have help generating better documentation for gplots
and the other r-gregmisc packages...
…On Tue, Mar 10, 2020 at 10:29 AM Steffen Möller ***@***.***> wrote:
I am not sure. The script may be more work than the vignette and I presume
that whoever starts writing the vignette is also likely to get ideas on how
to improve the man page. A script would have the advantage to give it all
some consistency - maybe we should just start with a few and then see if we
can somehow find some common motifs in these vignettes.
It may be helpful to start with a motivation for each diagram, which may
not be part of what the man page provides. That motivation would then offer
phrases that are likely to match search queries, like - "For comparing
observations that share many numerical attributes, a heatmap may be the
method of choice. There is no rule of thumb to the limits of observations
or attributes since observations and attributes can be reordered and the
human interpreter thus has the opportunity to compare aggregations (visual
"blocks") instead of individual lines or columns. Over the default heatmap,
this reimplementation grants extra freedom for .... ". If something like
this is what we are aiming at then this does not fit the more
vendor-neutral man pages.
Google once discussed a GSoC for documentation writing. Sounds like a nice
fit. Also we could have this for the Google Code-in.
—
You are receiving this because you modified the open/close state.
Reply to this email directly, view it on GitHub
<#3?email_source=notifications&email_token=ABO4GXYXOXYKVCVHY22JXGLRGZFEPA5CNFSM4LALOIV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEOLUNKY#issuecomment-597116587>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABO4GX2OEFLYXBTX64SZT23RGZFEPANCNFSM4LALOIVQ>
.
--
"Whereas true religion and good morals are the only solid foundations of
public liberty and happiness . . . it is hereby earnestly recommended to
the several States to take the most effectual measures for the
encouragement thereof." Continental Congress, 1778
|
Search engines find the PDFs from CRAN. Having all of gplots covered with a short example how the function/plot may be used, should be of considerable help for newcomers.
The text was updated successfully, but these errors were encountered: