Skip to content
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

Add a reference to the API documentation and introduce the concept #822

Open
wants to merge 2 commits into
base: gh-pages
Choose a base branch
from

Conversation

cgaylord-vt
Copy link

@cgaylord-vt cgaylord-vt commented May 14, 2020

Please delete this line and the text below before submitting your contribution.


Thanks for contributing! If this contribution is for instructor training, please send an email to checkout@carpentries.org with a link to this contribution so we can record your progress. You’ve completed your contribution step for instructor checkout just by submitting this contribution.

Please keep in mind that lesson maintainers are volunteers and it may be some time before they can respond to your contribution. Although not all contributions can be incorporated into the lesson materials, we appreciate your time and effort to improve the curriculum. If you have any questions about the lesson maintenance process or would like to volunteer your time as a contribution reviewer, please contact The Carpentries Team at team@carpentries.org.


Clark Gaylord and others added 2 commits Apr 26, 2020
@cgaylord-vt
Copy link
Author

@cgaylord-vt cgaylord-vt commented May 14, 2020

In my experience, when novices first see something like add_subplot they find it to be magic: "how did you know that's how to use it", etc. I think this is a good place to introduce the concept that there are reference materials to refer to when writing code, both to understand the process of finding functionality as well as specifics of how that functionality works.

@ldko
Copy link
Contributor

@ldko ldko commented May 19, 2020

Hi @cgaylord-vt thank you for your contribution of opening this pull request. I agree with your noted experience of novices wondering how you know how to use a function or method. I think your explanation ties in with the Mystery Functions in IPython callout that is in episode 2 where the solution given there is to get information via help or ?. I think it might be helpful to bring up documentation here. There is also an issue open (#769) about possibly moving this explanation earlier and a comment about changing the name of the callout. I am wondering what you @cgaylord-vt and other maintainers @maxim-belkin @annefou think about putting the explanation of documentation with this content and possibly moving it earlier (and renaming).

Regarding the text you have included about documentation, I think if we mention "API" we perhaps need to link it to an entry in the glossary, as I suspect this is a term that novices may not know. Let's see if we can get other feedback about this. Thanks again for your work on this @cgaylord-vt !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants