Many small vignettes

[smoe]

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.

[warnes]

That's a great idea. We'll put it on the todo list.

[warnes]

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 notifications@github.com 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 https://github.com/r-gregmisc/gplots/issues/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

[smoe]

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.

[warnes]

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 notifications@github.com 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 https://github.com/r-gregmisc/gplots/issues/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