Suggested improvements for Aside: Getting Help

[CarolynKoehn]

How could the content be improved?

A few open issues pertain to the Aside: Getting Help section in Episode 3 "Exploring and understanding data."

1. Per @JCSzamosi in [Pilot workshop feedback]:  #900: "When talking about looking at help documents and defining arguments, I think it would be better to choose something that isn't a generic method. The documentation of head() contains a lot of extraneous stuff that I think it out of scope for the workshop and gets in the way of explaining argument definitions, order, default values, etc."
2. @ha0ye suggests the addition of screenshots and description for navigating help documents in Introduce "reading help pages" in Episode 1 Intro to R #719: "It would be helpful to add some screenshots and description of navigating the documentation file and pull out important information: (1) which package the function is from, (2) longer-form description, (3) function arguments and default values, (4) return value, (5) examples"

Which part of the content does your suggestion apply to?

episodes/how-r-thinks-about-data.Rmd

[ha0ye]

In (re)-starting the discussion on this topic, I'd like to start by breaking down the topic of "reading help pages" into more fine-grained component skills or tasks.

• general introduction to the format of help pages and how they structure information
• overview of ways in which to use help pages:
  • understanding what a function does ("I encountered this in code, and I don't know what it does")
  • fixing an error in using a function ("I used this function because I think it does X, and it didn't do X or resulted in an error")
  • improving or iterating on the usage of a function ("I used this function, and I expect there's an argument to get it to operate a little differently, but I don't know the syntax for changing the behavior of the function")
• identify which components of a help page will help with the specific tasks

[CarolynKoehn]

@ha0ye, that sounds great! The current verbiage in the lesson is:

To learn more about a function, you can type a ? in front of the name of the function, which will bring up the official documentation for that function: ?head
Function documentation is written by the authors of the functions, so they can vary pretty widely in their style and readability. The first section, Description, gives you a concise description of what the function does, but it may not always be enough. The Arguments section defines all the arguments for the function and is usually worth reading thoroughly. Finally, the Examples section at the end will often have some helpful examples that you can run to get a sense of what the function is doing.

Your suggestion to add a general introduction and overview of use cases seems like a useful addition. Would you like to take the lead on creating a PR for this?

[ha0ye]

Happy to lead a PR, and try to bump this up on my TODO list.

@JCSzamosi - do you have any thoughts to add to my breakdown of use cases above?

[JCSzamosi]

@ha0ye your outline looks great to me! The only thing I might add is an emphasis on looking at examples, when they exist, as a way to clarify what might be pretty impenetrable text in the help page. Feel free to tag me in your PR if you want more input, but I don't want to add another cook to that kitchen unnecessarily.