More-on-Documentation

[VarunK21]

This file contains how and why to read the documentations of any library you are using in your program or code.

[arm61]

Hey @VarunK21, before I take a look at this can you move it into either a markdown file or a Jupiter notebook (since there is no code the markdown should suffice).

I will try and find time to read it today.

[arm61]

Additionally the file should be in the appropriate folder in the content directory, see https://github.com/pythoninchemistry/intro_python_chemists/blob/master/content/contributing.md

[arm61]

Also it has been brought to my attention that the descriptions of the libraries are copy and pasted from https://www.ubuntupit.com/best-python-libraries-and-packages-for-beginners/ or wikipedia, is it possible that you can use your own words to describe the function of the package? We are trying to create original content. Not copy from others, or indeed paraphrase.

[arm61]

@VarunK21 please note the copyright policy of ubuntupit (https://www.ubuntupit.com/copyright-policy/).

[VarunK21]

@arm61 I will rewrite the descriptions in my own words and will put the file in the correct directory. And will get back to you soon

[VarunK21]

Please have a look at this @arm61 and suggest me the changes if any .

[arm61]

I am crazy busy this whole week, then off on Monday. So if @j-m-dean or @alexsquires have a chance to look at this feel free. If not I can deal with it next week.

[alexsquires]

I appreciate the wide range of packages discussed explicitly. While some are currently not used in the book (such as sympy and pandas), the 'commonly used packages' section is a nice touch, and is easily modified to include whatever packages we deem of interest as the project evolves.

Before compiling a list of suggested changes, I'd like to make two points about this document as it stands, and see if the other contributors agree (@arm61 @j-m-dean ):

• I do not like the use of gendered pronouns (i.e. him), this should not be an issue if adhering to the style guide but perhaps worth stating there explicitly?
• I don't feel comfortable promoting the use of devdocs as it seems much of the documentation contained within is outdated, or key packages are not included (i.e. there most up-to-date entries for matplotlib and numpy are ~1 year old, and scipy is not covered.). I think, for our target audience, the official package documentation should suffice.

[j-m-dean]

I agree with @alexsquires . With regards to the two points raised:

• We wish to help facilitate the education of every student throughout this project; the use of gendered pronouns can discourage some. When I write my contributions, I aim to use "they/the individual/this person" to, hopefully, encapsulate every student who may be interested in this course. This should be in the style guide, as suggested, so future contributors are aware.

• As the documentation is outdated on devdocs, it would be easier for students to access the most appropriate documentation directly from the developers. The official documentations for all modules discussed are freely available online. Therefore, I would not recommend promoting devdocs to be used by students.

[VarunK21]

@alexsquires and @j-m-dean thanks for your valuable suggestions. I would perform the mentioned changes in the documentation and will get back to you soon.

[VarunK21]

@arm61 @j-m-dean @alexsquires I need some suggestions regarding the documentation
Should I remove the libraries sympy and pandas from the list as they are not yet used in the book ?

[arm61]

Yes I think so.

Also remember the focus of the section is to introduce students how to understand the docs. These contain technical writing that those new to programming may not be familiar with.

[VarunK21]

Please have a look at the latest documentation i have uploaded I have tried my best and kept all the points mentioned by you all while writing this . But still if there are any changes required the do tell me .
@arm61 @j-m-dean @alexsquires

[alexsquires]

Hi @VarunK21,

Sorry this took so long! A couple of technical points:

A reminder of @arm61 's point:

Additionally the file should be in the appropriate folder in the content directory, see https://github.com/pythoninchemistry/intro_python_chemists/blob/master/content/contributing.md

Secondly, could your include your images in images as opposed to stored internally within the notebook (see and_or.ipynb or collections.ipynb for a couple of examples).

Corrections:

• Your punctuation is always preceded by a space, i.e. a sentence is completed with' .' as opposed to the expected'.'
• cell 6: Data Visualisation should not be capitalised, cahrts -> charts
• cell 8: delete 'ehose'
• cell 9: Machine and Data should not be capitalised, and and a space after preprocessing
• cell 12: some of this cell has been converted to a monospaced type face could this be converted to standard font?

[VarunK21]

@alexsquires I am extremely sorry as it took me a little longer to reply. I will soon correct the above mentioned points and upload the required file for review. Could you also please elaborate what you want me to do with the images in the documentation.

[alexsquires]

So, as opposed to including the images within the notebook, they should be added to intro_python_chemists/content/images. If you are unsure of how then to get them to appear in the notebook, both and_or.ipynb and collections.ipynb have examples of this.