Updates to Content Guidelines #171

kelle · 2017-09-29T18:33:20Z

No description provided.

eblur

Looks good! I made minor suggestions for word choice.

eblur · 2017-09-29T18:37:11Z

CONTRIBUTING.md

-  - [astropy.coordinates](http://docs.astropy.org/en/stable/coordinates/)
-  - [astroquery](https://astroquery.readthedocs.io/en/latest/)
-
+    - use [astropy.visualization](http://docs.astropy.org/en/stable/visualization/) 


where possible

eblur · 2017-09-29T18:57:45Z

CONTRIBUTING.md

 - Roughly follow this progression:
  - Intput/Output: read in some data 
+    - use [astroquery](https://astroquery.readthedocs.io/en/latest/) where possible
  - Analysis: do something insightful/useful 


eblur · 2017-09-29T19:08:53Z

CONTRIBUTING.md

 - Demonstrate best practices of variable names. 
   - Variables should be all lower case with words separated by underscores.
   - Variable names should be descriptive. E.g., galaxy_mass, u_mag.
+- Use explicit print statements


Use the print function explicitly

(suggested wording)

eblur · 2017-09-29T19:09:38Z

CONTRIBUTING.md

- Compile a list of the functions and packages the tutorial demonstartes and include a short a description with the pull request.
+Narrative:
+- Please read through the other tutorials to get a sense of the desired tone and length. 
+- Use [Markdown formatting](http://jupyter-notebook.readthedocs.io/en/latest/examples/Notebook/Working%20With%20Markdown%20Cells.html) in text cells for formatting, links, latex, and code snippets. 


[Jupiter markdown formatting]

eblur · 2017-09-29T19:10:14Z

CONTRIBUTING.md

+Narrative:
+- Please read through the other tutorials to get a sense of the desired tone and length. 
+- Use [Markdown formatting](http://jupyter-notebook.readthedocs.io/en/latest/examples/Notebook/Working%20With%20Markdown%20Cells.html) in text cells for formatting, links, latex, and code snippets. 
+- Title should be short and descrictive


typo: "descriptive"

eblur · 2017-09-29T19:10:54Z

CONTRIBUTING.md

+- Please read through the other tutorials to get a sense of the desired tone and length. 
+- Use [Markdown formatting](http://jupyter-notebook.readthedocs.io/en/latest/examples/Notebook/Working%20With%20Markdown%20Cells.html) in text cells for formatting, links, latex, and code snippets. 
+- Title should be short and descrictive
+- List all author's full names (comma separated) and link to github profile and/or ORCID id.


eblur · 2017-09-29T19:14:21Z

CONTRIBUTING.md

 - As much as possible, comply with [PEP8](https://www.python.org/dev/peps/pep-0008/)
+- Imports
+Do not import `*`. Import package and functions explicitly. 


Something is weird with the formatting. Use linebreak.

eblur · 2017-09-29T19:16:49Z

CONTRIBUTING.md

+import astropy.units as u
+import astropy.coordinates as coord
+from astropy.io import fits
+


This code block could use a small title. Perhaps Suggested import abbreviations

bsipocz · 2017-09-29T20:50:37Z

@kelle - Could you add a point about not including output and execution number in the notebooks? The current WIP ones are full of those.

astrofrog · 2017-10-01T17:09:15Z

CONTRIBUTING.md

+  - Recommended import block and abbreviations
+    ```python
+    import numpy as np
+    import matplotlib as mpl


Also import matplotlib.pyplot as plt

astrofrog · 2017-10-01T17:11:04Z

I think we should also decide on the all imports at top vs imports inline, since there are also different opinions here and it would be good to be consistent either way.

I removed a bunch of text and added links to more github help pages.

adrn · 2017-10-02T00:18:52Z

CONTRIBUTING.md

+Example, example, example
+
+## Companion Content
+Carroll & Ostlie 10.3, Binney & Tremian 1.5


Tremian -> Tremaine

adrn · 2017-10-02T00:19:16Z

CONTRIBUTING.md

+## Companion Content
+Carroll & Ostlie 10.3, Binney & Tremian 1.5
+
+This tutorial goes from a downloading a data file, doing something to it, and visualizing it.


"This tutorial goes from a downloading..." -> "This tutorial goes from downloading..."

adrn · 2017-10-02T00:20:28Z

CONTRIBUTING.md

-Remember to place any extra files
-used by the tutorial in the directory with the notebook file, and place them
-under git version control.
+notebook file itself -- should go in this directory. 

 You will also need to edit the notebook file metadata.


We actually don't use the metadata anymore -- we should consider just asking the contributors to add this info to the first cell in a pre-formatted block?

deleted for now. when we know what we want them to do, we can add the instructions.

adrn · 2017-10-02T00:20:51Z

CONTRIBUTING.md

 - date (month year, e.g. 'July 2013')

 Here is an example of one of these files: [FITS-header.ipynb](https://github.com/astropy/astropy-tutorials/blob/master/tutorials/FITS-header/FITS-header.ipynb) (be sure to hit the "raw" button to see the metadata).

-You will also need to specify any python packages that the tutorial depends on.
+Please specify any python packages that the tutorial depends on via the `requirements.json` file.


This will change as well, but I'm fine leaving this & merging and then I can rebase my PR (#153) and update with the new info.

adrn · 2017-10-02T00:22:27Z

CONTRIBUTING.md

+Narrative:
+- Please read through the other tutorials to get a sense of the desired tone and length. 
+- Use [Markdown formatting](http://jupyter-notebook.readthedocs.io/en/latest/examples/Notebook/Working%20With%20Markdown%20Cells.html) in text cells for formatting, links, latex, and code snippets. 
+- Title should be short and descrictive


"decrictive" -> "descriptive"

adrn · 2017-10-02T00:23:05Z

CONTRIBUTING.md

+- Please read through the other tutorials to get a sense of the desired tone and length. 
+- Use [Markdown formatting](http://jupyter-notebook.readthedocs.io/en/latest/examples/Notebook/Working%20With%20Markdown%20Cells.html) in text cells for formatting, links, latex, and code snippets. 
+- Title should be short and descrictive
+- List all author's full names (comma separated) and link to github profile and/or [ORCID](https://github.com/astropy/astropy-tutorials/pull/171) id.


Did you mean to link to this PR for ORCID? also is "ORCID id" redundant?

They call it an ORCID iD: https://orcid.org/register

adrn · 2017-10-03T01:49:18Z

I think we should also decide on the all imports at top vs imports inline, since there are also different opinions here and it would be good to be consistent either way.

I prefer imports at top

kelle · 2017-10-03T02:37:24Z

I also prefer imports at the top. It promotes good coding practice and I like the foreshadowing.

adrn · 2017-11-17T03:32:11Z

Ok, this looks better than what is there now, and I want to make this a part of the tutorials documentation page so I'm going to merge. Thanks @kelle!

Updates to Content Guidelines

b5c601d

kelle requested a review from eblur September 29, 2017 18:33

kelle added 2 commits September 29, 2017 13:56

Commands for Section Headings

b21f7f0

import guidelines

b72e52e

kelle mentioned this pull request Sep 29, 2017

Make style guide for tutorials #169

Closed

eblur reviewed Sep 29, 2017

View reviewed changes

code guidelines and import polish #169

86488a2

astrofrog reviewed Oct 1, 2017

View reviewed changes

kelle added 2 commits October 1, 2017 16:09

add template for header

e7c4526

trim down github instructions.

1a71323

I removed a bunch of text and added links to more github help pages.

adrn requested changes Oct 2, 2017

View reviewed changes

typos, more on Title, less on metadata

35cbf69

adrn mentioned this pull request Oct 22, 2017

Move content from CONTRIBUTING.md to developer docs #173

Closed

adrn approved these changes Nov 17, 2017

View reviewed changes

adrn merged commit 910cc51 into master Nov 17, 2017

eteq deleted the kelle-contributing-update branch March 7, 2018 17:33

Updates to Content Guidelines #171

Updates to Content Guidelines #171

Uh oh!

Conversation

kelle commented Sep 29, 2017

Uh oh!

eblur left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bsipocz commented Sep 29, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

astrofrog commented Oct 1, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adrn commented Oct 3, 2017

Uh oh!

kelle commented Oct 3, 2017

Uh oh!

adrn commented Nov 17, 2017

Uh oh!

Uh oh!